diff --git a/.github/workflows/deploy-prod.yml b/.github/workflows/deploy-prod.yml index 96547653..25125c6f 100644 --- a/.github/workflows/deploy-prod.yml +++ b/.github/workflows/deploy-prod.yml @@ -90,7 +90,7 @@ jobs: run: cp docs/.env.example docs/.env - name: Build Image - run: docker compose -f docker-compose.dev.yml build + run: docker compose build - name: Push Image to Docker Hub - run: docker compose -f docker-compose.dev.yml push + run: docker compose push diff --git a/.github/workflows/pull-images.yml b/.github/workflows/pull-images.yml index c70fb5bc..52d13d31 100644 --- a/.github/workflows/pull-images.yml +++ b/.github/workflows/pull-images.yml @@ -26,4 +26,4 @@ jobs: run: cp docs/.env.example docs/.env - name: Pull Development Image - run: docker compose -f docker-compose.dev.yml pull + run: docker compose pull diff --git a/README.md b/README.md index 97126df1..f1707c65 100644 --- a/README.md +++ b/README.md @@ -70,13 +70,13 @@ The app depends these libraries and frameworks. 2. (Optional) Run the app for local development using Docker. Navigate to the project's root directory then run:
``` # 2.1. Build the client and server containers for localhost development. - docker compose -f docker-compose.dev.yml build + docker compose build # 2.2. Create and start the development client and server containers - docker compose -f docker-compose.dev.yml up + docker compose up # 2.3. Stop and remove the development containers, networks, images and volumes - docker compose -f docker-compose.dev.yml down + docker compose down ``` 3. Add or edit MDX files in the `/pages` directory, or add React components in the `/components` directory. @@ -111,13 +111,13 @@ https://hub.docker.com/r/acaptutorials/acaptutorials.github.io 1. Pull the development Docker image from Docker Hub using one of the options.
- `docker pull acaptutorials/acaptutorials.github.io:latest` - - `docker compose -f docker-compose.dev.yml pull` (using Docker compose from the root project directory) + - `docker compose pull` (using Docker compose from the root project directory) 2. Navigate to the project directory using the command line. Create a `.env` file inside the **/docs** directory with reference to the `.env.example` file. - See [Usage](#usage) - **step # 2** for more information. 3. Run the development Docker image.
-`docker compose -f docker-compose.dev.yml up` +`docker compose up` 4. (Optional) Run the development Docker image (from other directories).
`docker run -it --rm -p 3000:3000 acaptutorials/acaptutorials.github.io:latest` @@ -125,13 +125,13 @@ https://hub.docker.com/r/acaptutorials/acaptutorials.github.io ### Build the Development Docker Image 1. Build the development Docker image on your machine.
-`docker compose -f docker-compose.dev.yml build` +`docker compose build` 2. Navigate to the project directory using the command line. Create a `.env` file inside the **/docs** directory with reference to the `.env.example` file. - See [Usage](#usage) - **step # 2** for more information. 3. Run the development Docker image.
-`docker compose -f docker-compose.dev.yml up` +`docker compose up` ## Usage with GitHub Actions @@ -155,6 +155,7 @@ https://hub.docker.com/r/acaptutorials/acaptutorials.github.io | --- | --- | | DOCKERHUB_USERNAME | Docker Hub username | | DOCKERHUB_TOKEN | Deploy token for the Docker Hub account | +| FIREBASE_TOKEN | Firebase CI token for deployment to Firebase Hosting | #### GitHub Variables diff --git a/docker-compose.dev.yml b/docker-compose.yml similarity index 100% rename from docker-compose.dev.yml rename to docker-compose.yml diff --git a/docs/pages/announcements.mdx b/docs/pages/announcements.mdx index ec1351c5..b971df66 100644 --- a/docs/pages/announcements.mdx +++ b/docs/pages/announcements.mdx @@ -9,3 +9,9 @@ import { Cards, Image } from 'nextra/components' <>![Documentation theme](/assets/docs-theme.png) + + + + <>![Documentation theme](/assets/docs-theme.png) + + \ No newline at end of file diff --git a/docs/pages/announcements/_meta.json b/docs/pages/announcements/_meta.json index dd0947cb..1d6704a7 100644 --- a/docs/pages/announcements/_meta.json +++ b/docs/pages/announcements/_meta.json @@ -2,5 +2,9 @@ "firebase-storage-2024": { "title": "Firebase Storage Pricing Plan Changes (2024)", "type": "page" + }, + "pagasa-10day-excel": { + "title": "PAGASA 10-Day Excel Files Discontinued", + "type": "page" } } diff --git a/docs/pages/announcements/pagasa-10day-excel.mdx b/docs/pages/announcements/pagasa-10day-excel.mdx new file mode 100644 index 00000000..d49a3f84 --- /dev/null +++ b/docs/pages/announcements/pagasa-10day-excel.mdx @@ -0,0 +1,126 @@ +import { useEffect, useState, useMemo } from 'react' +import { useTheme } from 'next-themes' +import { Callout } from 'nextra/components' + +export function FAQBox({ title, children, open = false, color = '' }) { + // Copied from /articles/provinces-municipalities.mdx + const [isClient, setIsClient] = useState(false) + const { theme, resolvedTheme } = useTheme() + + useEffect(() => { + setIsClient(true) + }, []) + + const detailsBgStyle = useMemo(() => { + const bg = resolvedTheme === 'dark' + ? 'bg-neutral-800' + : 'bg-neutral-50' + + return `last-of-type:mb-0 rounded-lg ${bg} p-2 mt-4` + }, [resolvedTheme]) + + return !isClient + ?
...
+ : ( +
+ + {title} + +
{children}
+
+ ) +} + +# PAGASA 10-Day Excel Files Discontinued + +**Effective August 31, 2025** + +## What's Changing + + +Starting **August 31, 2025**, PAGASA will no longer provide its **10-Day Weather Forecast in Excel format**. +Instead, all forecasts will be delivered through the new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) launched in **July 2025**. +This means any ACAP process, report, or system that currently relies on downloading Excel files will cease to function unless updated to use the API. + +_Note: PAGASA has not announced plans to archive past Excel files._ + + +
+Click to view the attached screenshot of PAGASA's announcement for more information. +![PAGASA 10-Day Excel files discontinuation announcement](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FNOZHqk2E8F8RoVvZuVVv_file?alt=media&token=88bd0b49-b7ee-45f8-843e-11bd0b9dcfe6) + + +[alternate screenshot](https://private-user-images.githubusercontent.com/30580083/481051514-2d333f63-8fc4-4d81-a8da-d0ff48698c5e.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NTY1MzczNTAsIm5iZiI6MTc1NjUzNzA1MCwicGF0aCI6Ii8zMDU4MDA4My80ODEwNTE1MTQtMmQzMzNmNjMtOGZjNC00ZDgxLWE4ZGEtZDBmZjQ4Njk4YzVlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNTA4MzAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjUwODMwVDA2NTczMFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTVkNDUzZmI0NjVhMTQxOWZhMmUxZDU4YmQ5ZTc1N2EzOGUwMWE1N2VlNWFhNGI3ODA4MTNkZDVmZDg5MjEwYzEmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.cUM-tiJyihJq5r8zyiTXW_h3_Astl3obI-XvymTy684) + + +
+ +## FAQs + +The following FAQs explain who will be affected, why this change is happening, and how projects should prepare. + + +Projects that use the **PAGASA 10-Day Weather Forecast Excel files**. + +It includes **components in acap-v2** ([ACAP 2.0](/changelog/#version-2-acap-20)) and **climate-services-webportal-v1** ([ACAP 1.0](/changelog/#version-1-acap-10)), plus any forks, scripts, or automated tasks fetching Excel-based forecasts: + +1. [Provinces and municipalities listing](/articles/provinces-municipalities/) +2. [10-Day Weather Forecast data](/post-installation/weather-forecasts/tenday-forecast/) +3. _([ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) - if these APIs are activated)_ +4. Automated scripts/workflows + + +After **August 31, 2025**, all workflows relying on Excel files will fail unless updated to use the API. + + + + + +PAGASA is modernizing data sharing by moving from Excel files to REST APIs, reducing brittle manual steps, and enabling more robust integrations. + +The new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) (launched July 2025) covers both **10-Day** and **Seasonal weather forecasts**. + + +It is not yet known whether PAGASA will also discontinue the [**Seasonal Weather Forecast Excel files**](/post-installation/weather-forecasts/seasonal-forecast/#pagasa-seasonal-weather-forecast-excel-file). + + + + + + +There are currently no news or directives for syncing the parent **acap-v2** code repository to the **PAGASA TenDay API**. Projects using it as base template (including ACAP Bicol) are advised to sync their ACAPs to the API until futher notice. + + +Here are the recommended migration steps for syncing ACAP to the PAGASA TenDay API. However, feel free to adjust and customize as deemed necessary. + +1. Review the [PAGASA TenDay API documentation](https://tenday.pagasa.dost.gov.ph/docs). +2. Request an **API key** from PAGASA. +3. **Regional location data:** Build the provinces and municipalities list from the PAGASA TenDay API, possibly from its **Validation - Location** endpoint at `"https://tenday.pagasa.dost.gov.ph/api/v1/location"`. +4. **Data source:** Replace the **10-Day weather forecast Excel file** fetch/parse logic with **TenDay API REST responses**. +5. Update scripts β€” Excel downloads will stop after August 31, 2025. + + +**Tip:** ACAP (1.0 until version 2.0 - 2.1) processes its **provinces and municipalities list** and **10-day weather forecast data** using the `"npm run cron:tenday"` NPM script, under the `"/server/src/scripts/cron/update_tenday_weather"` folder. + +Inspect and customize scripts in this folder to sync with the PAGASA TenDay API. + +Revisiting ACAP's architecture diagrams in the root `README` and `"/server/src/scripts/generate-docs/templates/img-acap.png"` may also help. + + + + + +Visit these references to learn more about the changes. + +- [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) +- [10-Day Weather Forecast](/post-installation/weather-forecasts/tenday-forecast/) +- [Provinces and Municipalities](/articles/provinces-municipalities) +- [ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) + + +--- + +*Disclaimer: This documentation update does not imply ongoing involvement with the project.* \ No newline at end of file diff --git a/docs/pages/articles.mdx b/docs/pages/articles.mdx new file mode 100644 index 00000000..2a20065a --- /dev/null +++ b/docs/pages/articles.mdx @@ -0,0 +1,16 @@ +import { Cards, Card, FileTree } from 'nextra/components' + +# Articles + +A collection of articles and notes about development and other details. + +
+ + + + + + + + + diff --git a/docs/pages/articles/deployment.mdx b/docs/pages/articles/deployment.mdx index 32c7bc1a..ed6d4d56 100644 --- a/docs/pages/articles/deployment.mdx +++ b/docs/pages/articles/deployment.mdx @@ -10,6 +10,13 @@ These videos created for ACAP's initial release (ACAP 1.0) back in **2023** shou Follow the steps in the **Render Initial Blueprint Instance** section to sync its Render deployment methods with the ACAP 2.0 updates. +## Git Flow + +CI/CD using GitHub Actions deploy code updates to the **development** or **production** environments following this [simplified version of Git Flow](https://youtu.be/cV-9KszXEyw?feature=shared&t=845). Refer to the [Git Flow](/post-installation/git-flow) page for more information about this process. + +
+ +acap-git-flow ## Render Initial Blueprint Instance diff --git a/docs/pages/articles/provinces-municipalities.mdx b/docs/pages/articles/provinces-municipalities.mdx index ace3db41..bc1f2d22 100644 --- a/docs/pages/articles/provinces-municipalities.mdx +++ b/docs/pages/articles/provinces-municipalities.mdx @@ -39,6 +39,10 @@ export function FAQBox({ title, children, open = false }) { ACAP uses a combination of the [PAGASA 10-day weather forecast Excel files](https://www.pagasa.dost.gov.ph/climate/climate-prediction/10-day-climate-forecast) and the [PAGASA Seasonal Forecast- Forecast Rainfall Analysis Table](https://www.pagasa.dost.gov.ph/climate/climate-prediction/seasonal-forecast) as a data source for its region, provinces, and municipalities list. + +Starting **August 31, 2025**, PAGASA will no longer provide the **10-Day Excel files**. Check the [Announcements](/announcements/pagasa-10day-excel) section for more information. + + ## FAQs diff --git a/docs/pages/post-installation.mdx b/docs/pages/post-installation.mdx index 0b661177..f5f4e12a 100644 --- a/docs/pages/post-installation.mdx +++ b/docs/pages/post-installation.mdx @@ -2,11 +2,11 @@ import { Cards, Card, Callout } from 'nextra/components' # Post-Installation -These tutorials contain additional post-installation instructions after initially setting up the client and server apps in the [Installation](/installation) section. +These tutorials contain additional post-installation instructions and guidelines after initially setting up the client and server apps in the [Installation](/installation) section.
-### Immediate +### ⚑ Immediate @@ -17,10 +17,19 @@ These tutorials contain additional post-installation instructions after initiall -### Optional +### ✨ Optional + +
+ +### πŸ’‘ During Development + + + + + \ No newline at end of file diff --git a/docs/pages/post-installation/_meta.json b/docs/pages/post-installation/_meta.json index bb1af904..e0cd7b5d 100644 --- a/docs/pages/post-installation/_meta.json +++ b/docs/pages/post-installation/_meta.json @@ -7,5 +7,7 @@ "acap-rcmas-api": "ACAP-RCMAS REST APIs", "opengraph": "Opengraph Settings", "google-search": "Google Search Console", - "province-codes": "Province Codes" + "province-codes": "Province Codes", + "git-flow": "Git Flow", + "site-search": "Site Search" } diff --git a/docs/pages/post-installation/git-flow.mdx b/docs/pages/post-installation/git-flow.mdx new file mode 100644 index 00000000..a2e9f8b4 --- /dev/null +++ b/docs/pages/post-installation/git-flow.mdx @@ -0,0 +1,53 @@ +import { Callout, Steps } from 'nextra/components' + +# Git Flow + +This page **summarizes the simplified version of Git Flow** branching strategy from the [ACAP video tutorials](https://youtu.be/cV-9KszXEyw?feature=shared&t=845) when developing new features, bug fixes or tasks. + +CI/CD using GitHub Actions deploy code updates to the **development** or **production** environments on certain triggers (eg., merging PRs to the dev branch or creating new Releases). + +
+ +acap-git-flow + + +**(Optional)** Before proceeding, create a GitHub Issue describing the new feature, bug fix or task that you'll develop. This tracks and organizes the details of the incoming updates. + + + +### Create a feature branch + +- Create a **feature branch** branching out from the **dev branch** + + > If a GitHub Issue describes this feature, name the branch with the GitHub Issue number eg., `feat/acaptutorials-12` (Issue #12) + + ```sh + git checkout dev + git checkout -b feat/acaptutorials-12 + + # Using other branch names + # git checkout -b awesome-update + ``` + +- This isolates new work (feature, bug fix, or task) so it doesn't destabilize the shared development branch. + +### Merge the feature branch back to dev + +- Once the feature is complete and reviewed via a **Pull Request (PR)**, it's merged back into **dev**. +- Approving a PR to the dev branch (or pushing updates directly to the dev branch) triggers a deployment to the **development** (Firebase Hosting, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. +- It allows testing the feature with other in-progress features in an integrated (development) environment. +- Delete the feature branch afterward to keep the repository clean. + +### Promote dev to master + +- When the **dev branch** has accumulated stable, tested features, create a Pull Request (PR) to **master** +- The master branch always reflects the code that's safe to release to production. + +### Tag a release + +- Tag and version a release from the **master branch** (e.g., v1.0.0). +- This creates an immutable snapshot of the code that corresponds to a specific release. +- It also triggers a deployment to the **production** (GitHub Pages, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. + + + diff --git a/docs/pages/post-installation/site-search.mdx b/docs/pages/post-installation/site-search.mdx new file mode 100644 index 00000000..902bc2a9 --- /dev/null +++ b/docs/pages/post-installation/site-search.mdx @@ -0,0 +1,136 @@ +import { Callout, Steps } from 'nextra/components' + +# Search Bar: Site Search + +![search bar keywords](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FlE08vZGvNmHuOT870iFR_file?alt=media&token=cc3d3bec-739e-4f0d-8a63-8b6b3f0f2891) + +## Introduction + +This guide shows how to make **new public pages** searchable via the site's **Search Bar** by updating `data.js` and **running a keyword indexer script**. ACAP configures this feature via a script in`/server/src/scripts/page_indexer/`. + + +**`npm run build:page_index`** indexes keywords from live public pages defined in `data.js` and saves them to the database. It runs automatically after deployment, but you can also run it locally for testing. + + + +**Optional:** Only needed when adding **new public pages** or updating existing ones for search indexing. + +> **INFO:** The search method and keyword extraction process are expected to extract keywords only from simple static pages. Pages with longer or complex content may require a different approach. + + +## Add a Page to Search + +(Quick summary) + +1. Add `id` attributes to text containers in your page. +2. Update `data.js` with path, name, info, and selectors. +3. Run `npm run build:page_index` locally to test. +4. Commit and push changes. +5. Deploy and verify search results. + +## Detailed Steps + + + +### Prepare the new public page for indexing + +- Add unique HTML `id` attributes to the container `
` of target elements with text content that you'd like to extract keywords from. +- For example, if there is a new **About Us** page: + +```jsx copy +return ( + + Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor... + +) +``` + +### Inspect the public pages file definition + +- Open the `"/server/src/scripts/page_indexer/data.js"` file. +- Observe the Object structure of the elements in the `sites[]` array, eg., the entry for the public "Weather Services" page, + + ```js copy + const sites = [ + { + path: 'weather-services', + name: 'ACAP Services', + info: 'Seasonal and 10-Day Weather Forecasts, and Special Weather Advisory', + selectors: [ + '#contents-seasonal-forecast', + '#contents-tenday-forecast', + '#contents-special-weather-forecast' + ] + }, + ... + ] + ``` + +
+ πŸ‘‰ Click to view the **`sites[]` Object key definitions** + + | Key | Definition | + | --- | --- | + | path | Frontend (NextJS) route to the target page | + | name | Page title | + | info | Short summary or description about the page | + | selectors | Array of HTML `id` attributes in the page in which to extract keywords from. Each element starts with a `#` | + +
+ + + - Failing to add appropriate `"selectors"` will skip indexing the search keywords. + - Ensure all public pages load correctly. There will be errors in indexing if a page is inaccessible or has loading errors. + + +### Add a new page file entry + +- Create a new entry in the `"/server/src/scripts/page_indexer/data.js"` file under the `sites[]` array corresponding to a newly-created public page. +- For example, to add the **About Us** page from **step #1**: + + ```js copy + const sites = [ + { + path: 'about-us', + name: 'About Us', + info: 'Information and details about our company', + selectors: ['#about-us-content'] + }, + ... + ] + +### Test extracting keywords + +- Set `LIVE_ORIGIN=http://localhost:3000` in the server `.env` +- Run the local website + ```sh copy + npm run dev + ``` + +- Open `http://localhost:3000` to verify the site is running. + +- Run the server NPM script + ```sh copy + npm run build:page_index + ``` + + Fix errors that may occur during this step. + +- If there are no errors in the previous step, type keyword(s) from the sample **About Us** page in the **Search Bar**, eg., + ```text copy + lorem ipsum + ``` + + The **About Us** page should display in the search results. + + ![site search success](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FUg972YCHQreS1jQVGmif_file?alt=media&token=55f400fa-cb64-4870-9ee0-5daceb702019) + +### Commit the `data.js` file + +If there are no errors in the previous steps and the search keyword(s) appear in **step #4**, proceed to commit and push the updated `data.js` file. + +### Deploy + +When you push changes, GitHub Actions will automatically run `npm run build:page_index` during deployment. Verify that the new keywords appear in the live Search Bar. + + diff --git a/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx b/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx index 7ecbf10e..df53d210 100644 --- a/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx +++ b/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx @@ -4,6 +4,10 @@ import { Callout, Steps } from 'nextra/components' ![pagasa-10day](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2Flct0mjyQ7jZqOvL9R9Bt_thumbnail?alt=media&token=73f8d105-ccfa-4654-bed3-5863db824bba) + +Starting **August 31, 2025**, PAGASA will no longer provide the **10-Day Excel files**. Check the [Announcements](/announcements/pagasa-10day-excel) section for more information. + + ## Introduction ACAP sources its 10-day weather forecast data from PAGASA's public 10-day weather forecast data (available as Excel files from day 1 - day 10) in their **10-Day Climate Forecast** web page at https://www.pagasa.dost.gov.ph/climate/climate-prediction/10-day-climate-forecast.