diff --git a/README.md b/README.md index d1bc8e2e..142709cc 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ ACAP Bicol (ACAP 2.0) development documentation. Built with [Nextra](https://nextra.site/), a modern static site generation framework running on NextJS. +> This project uses Nextra [version 2](https://nextra-v2-oe0zrpzjp-shud.vercel.app/). + ### Requirements The following dependencies are used for this project. Feel free to experiment using other dependencies and versions. @@ -20,7 +22,7 @@ The following dependencies are used for this project. Feel free to experiment us The app depends these libraries and frameworks. - NextJS v14.2.5 -- Nextra v2.13.4 +- Nextra v2.13.4 [[v2]](https://nextra-v2-oe0zrpzjp-shud.vercel.app/) - nextra-theme-docs v2.13.4 - React v18.3.1 - TailwindCSS v3.4.7 diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index 4f14683c..e2a4c2a6 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -1,5 +1,5 @@ services: - # NextJS v13 app running on development mode + # NextJS v14 app running on development mode acaptutorials.github.io-latest: container_name: acaptutorials-docs-latest image: acaptutorials/acaptutorials.github.io:latest diff --git a/docs/.env.example b/docs/.env.example index 40df7584..f3a97338 100644 --- a/docs/.env.example +++ b/docs/.env.example @@ -3,5 +3,5 @@ RELEASE_PAGE=https://github.com///banner.png BASE_URL=https://localhost:3000 -# Uncomment these 2 CHOKIDAR lines if using Docker Desktop and WSL2 on Windows OS +# Uncomment this line if using Docker Desktop and WSL2 on Windows OS # WATCHPACK_POLLING=true \ No newline at end of file diff --git a/docs/Dockerfile b/docs/Dockerfile index 94c8aa0e..a53075e2 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -1,4 +1,4 @@ -FROM node:20.15.0-alpine as base +FROM node:20.15.0-alpine AS base RUN mkdir -p /opt/docs WORKDIR /opt/docs RUN adduser -S client @@ -6,14 +6,14 @@ RUN chown -R client /opt/docs COPY package*.json ./ # BUILD TARGET -FROM base as build +FROM base AS build RUN npm install && npm cache clean --force COPY . ./ RUN npm run export USER client # DEVELOPMENT CLIENT PROFILE -FROM base as development +FROM base AS development ENV NODE_ENV=development RUN npm install && npm cache clean --force COPY . ./ @@ -21,7 +21,7 @@ EXPOSE 3000 CMD ["npm", "run", "dev"] # PRODUCTION CLIENT PROFILE -FROM nginx:1.22.0-alpine as production +FROM nginx:1.22.0-alpine AS production COPY --from=build /opt/docs/out /usr/share/nginx/html RUN rm /etc/nginx/conf.d/default.conf COPY config/nginx/nginx.conf /etc/nginx/conf.d diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index a64fe7e4..26b9a699 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -21,6 +21,10 @@ "type": "page", "newWindow": true }, + "announcements": { + "title": "Announcements", + "type": "page" + }, "video": { "title": "Video Tutorials", "type": "page" diff --git a/docs/pages/about.mdx b/docs/pages/about.mdx index e1b8cf20..d528d1ac 100644 --- a/docs/pages/about.mdx +++ b/docs/pages/about.mdx @@ -1,3 +1,3 @@ -# About +# About 💡 This site offers a more organized and structured approach to documenting the software development approaches for the Agro-Climatic Advisory Portal - Bicol (ACAP Bicol), initially released as ACAP 1.0 at the end of 2022 and now enhanced to version 2.0 as of 2024. diff --git a/docs/pages/announcements.mdx b/docs/pages/announcements.mdx new file mode 100644 index 00000000..4b072697 --- /dev/null +++ b/docs/pages/announcements.mdx @@ -0,0 +1,11 @@ +import { Cards, Image } from 'nextra/components' + +# Announcements 📣 + +
+ + + + <>![Documentation theme](/assets/docs-theme.png) + + diff --git a/docs/pages/announcements/_meta.json b/docs/pages/announcements/_meta.json new file mode 100644 index 00000000..dd0947cb --- /dev/null +++ b/docs/pages/announcements/_meta.json @@ -0,0 +1,6 @@ +{ + "firebase-storage-2024": { + "title": "Firebase Storage Pricing Plan Changes (2024)", + "type": "page" + } +} diff --git a/docs/pages/announcements/firebase-storage-2024.mdx b/docs/pages/announcements/firebase-storage-2024.mdx new file mode 100644 index 00000000..7bccafa9 --- /dev/null +++ b/docs/pages/announcements/firebase-storage-2024.mdx @@ -0,0 +1,158 @@ +import { useEffect, useState, useMemo } from 'react' +import { useTheme } from 'next-themes' +import { Callout } from 'nextra/components' + +export function FAQBox({ title, children, open = false }) { + // 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}
+
+ ) +} + +# Firebase Storage Pricing Plan Updates (2024) + +> _This article is a recap of the online meeting about changes to the Firebase Storage pricing plan held last October 14, 2024._ + +Firebase announced breaking changes regarding the no-cost pricing plan of their **Firebase Storage** service last September 2024. More information about this announcement is available in the [Cloud Storage Documentation for Firebase](https://firebase.google.cn/docs/storage/faqs-storage-changes-announced-sept-2024). + +## FAQs + + +[Firebase Storage](https://firebase.google.com/docs/storage), also known as _Firebase Cloud Storage_, is an online cloud storage service provided by Google Firebase. It is one (1) of the four (4) major Firebase components used by ACAP aside from the **Firestore Database** [[1]](https://firebase.google.com/docs/firestore/), **Firebase Authentication** [[3]](https://firebase.google.com/docs/auth/), and **Firebase Hosting** [[4]](https://firebase.google.com/docs/hosting/). + +ACAP uses the Firebase Storage for: + +- Hosting and uploading the generated PDF bulletin recommendations, allowing public PDF downloads in its PDF Bulletins Downloads page. +- Hosting and storing several frontend picture assets and files or the Home page's GEOJSON map file (as an alternate option for using MapBox). + + + +ACAP uses other Firebase components aside from the Firebase Storage. ACAP only uses the four (4) Firebase components among Firebase's [list of available](https://firebase.google.com/products-build) components/services: + +- **Firestore** (Database) [[1]](https://firebase.google.com/docs/firestore/) +- **Cloud Storage** (Firebase Storage) [[2]](https://firebase.google.com/docs/storage/) +- **Authentication** (Email/Password) [[3]](https://firebase.google.com/docs/auth/) +- **Hosting** [[4]](https://firebase.google.com/docs/hosting/) + + + +- Firebase will discontinue providing the standard (no-cost) Spark plan for Firebase Storage starting October 30, 2024 +- More information about this announcement is available at https://firebase.google.cn/docs/storage/faqs-storage-changes-announced-sept-2024. + + + + +Starting on October 30, 2024: + +- Initializing new Firebase Storage instances will require a payment method. It will require new Firebase projects subscribed to the Firebase pay-as-you-go Blaze plan by default. +- Existing ACAP Firebase Storage, created before October 30, 2024, will continue to work until October 2025. +- ACAP Firebase Storages not subscribed to the Firebase Blaze plan after October 2025 will cease to function unless they subscribe to the Blaze plan. +- ACAP Video Tutorials [[1]](https://youtu.be/gJESQaT0IBQ?si=fYA19J9OHiZR4V9X&t=127) regarding the Firebase Storage initialization will not work on Firebase projects subscribed to the standard (no-cost) Firebase plans + + + + +- No, this announcement only affects the Firebase Storage. Discontinued support of the Firebase standard (no-cost) pricing plan only affects the Firebase Storage. +- Other Firebase components used by ACAP - the Firestore Database, Firebase Authentication, and Firebase Hosting still retain their standard (no-cost) pricing plans until further announcements or changes by Google Firebase. + + +Subscribing to the Firebase Blaze Plan **will automatically enroll** all Firebase components to the pay-as-you-go Blaze plan, not just the Firebase Storage. + + + + +The Firebase pricing plan is accessible at https://firebase.google.com/pricing. + + +Subscribing to the Firebase Blaze Plan **will automatically enroll** all Firebase components to the pay-as-you-go Blaze plan, including other Firebase components not used by ACAP. + +ACAP only uses the following Firebase components among Firebase's [list of available](https://firebase.google.com/products-build) components/services: + +- **Firestore** (Database) [[1]](https://firebase.google.com/docs/firestore/) +- **Cloud Storage** (Firebase Storage) [[2]](https://firebase.google.com/docs/storage/) +- **Authentication** (Email/Password) [[3]](https://firebase.google.com/docs/auth/) +- **Hosting** [[4]](https://firebase.google.com/docs/hosting/) + +_All Firebase components service usage (including those not used by ACAP) will only reflect in the billing upon activation in the ACAP and usage beyond the no-cost Firebase plan._ + + + + + +- Subscribing to the Firebase pay-as-you-go Blaze plan requires creating a Google Cloud billing account and electing credit card information for the Firebase project. +- Billing subscriptions will only incur beyond standard (no-cost) usage/quotas of activated and used Firebase components/services enabled by developers. ACAP only expects usage from the **Firestore Database**, **Firebase Storage**, **Authentication**, and **Hosting** Firebase services. + + + Refer to the Firebase Pricing table for more information about the standard (no-cost) billing and usage quotas at + https://firebase.google.com/pricing + + +- Firebase usage analytics are accessible at this URL with or without a subscription to the Firebase Blaze plan: + + ```text + https://console.firebase.google.com/project//usage + ``` + + This page provides information for monitoring and providing insights, such as detailed pricing and usage of the active Firebase services used by the Firebase project. + + + ACAP expects usage only from the following Firebase services: **Firestore Database**, **Firebase Storage**, **Authentication**, and **Hosting**. [ACAP's Security guidelines](/security) only cover these four (4) Firebase components, aside from general web application security practices and know-how, e.g., stressing the need for data validation [[1]](/security/#database) [[2]](/directories/server). + + > Developers can use other Firebase components as deemed necessary when needed. However, since they are not included originally in the ACAP project Firebase components, developers should care about using them responsibly to avoid incurring Security issues and unexpected billing. + + + + + +Ensuring **system integrity** and **strong security measures** is critical when handling: + +1. Sensitive user information (e.g., full name and contact numbers) +2. Paid subscription to external services (e.g., Firebase, Semaphore) +3. Reliable and predictable information output + + +Before activating a paid Firebase subscription, consider whether unresolved [ACAP Security Technical Debts](/changelog#acap-2-security-debts) exist. If issues [[1]](https://github.com/amia-cis/acap-v2/issues/57) [[2]](https://github.com/amia-cis/acap-v2/issues/34) remain unaddressed, it may be beneficial to consult the lead ACAP programmer responsible for designing and implementing [ACAP 2.0](/changelog/#version-2-acap-20). Key topics to discuss include: + +- How security concerns introduced in ACAP 2.0+ are being addressed +- Plans for improving security and risk mitigation before enabling Firebase + + + +ACAP's [Security measures and practices for Firebase](/security) only cover the Firebase components that it actively uses: **Firestore Database**, **Firebase Storage**, **Authentication**, and **Hosting**. + +Developers are encouraged to learn more about responsible Security measures and practices for other Firebase components or services, should they feel the need to use [other Firebase services](https://firebase.google.com/products-build) (e.g., **Firebase ML**, **Cloud Functions**, **Extensions**, etc) for their ACAPs other than **four (4) main Firebase components** used by ACAP. + + + +## Firebase Storage Alternate Options + +The meeting discussed the following alternate options for ACAP's Firebase Storage component, considering the discontinuation of its no-cost pricing plan. + +1. Subscribe to the Firebase Blaze Plan +2. Integrate a new standard plan (free-tier) Cloud Storage Provider to replace Firebase Storage +3. Use the (Render) server file system for hosting PDFs diff --git a/docs/pages/changelog.mdx b/docs/pages/changelog.mdx index 3b96ab6c..042a2906 100644 --- a/docs/pages/changelog.mdx +++ b/docs/pages/changelog.mdx @@ -2,6 +2,8 @@ import { useEffect, useState, useMemo } from 'react' import { Callout, Steps } from 'nextra/components' import { useTheme } from 'next-themes' +import AnchorModal from '@/components/AnchorModal' + export function FAQBoxError({ title, children, open = false }) { const [isClient, setIsClient] = useState(false) const { theme, resolvedTheme } = useTheme() @@ -59,12 +61,20 @@ Version 2.0 and later versions may have new requirements that will thrive on new +
1. **Flexible Firestore Database Use:** Version 2.0+ adopted a more flexible approach for handling data management, facilitating faster feature development by performing _WRITE operations to the database directly from the web front end_ coupled with more _lenient Firestore database Rules_. However, this shift also introduced the potential for data to enter the database without the usual front-end controls through the [Firestore REST APIs](https://cloud.google.com/firestore/docs/reference/rest/). While this was not an issue in Version 1.0, it emerged as part of the effort to enhance development speed and feature delivery starting with Version 2.0. 2. **Cross-Site Scripting (XSS) Vulnerability in Crop Recommendations:** Related to item 1, the new process for editing WYSIWYG HTML-form crop recommendations input may allow unsafe or inaccurate content due to limited validation through the [Firestore REST APIs](https://cloud.google.com/firestore/docs/reference/rest/). Risks associated with this were recognized early in the process, but the focus on delivering core features led to a delay in integrating security measures. + + A YouTube video detailing steps for exploiting XSS vulnerabilities in the **ACAP 2.0 crop recommendations** at https://www.youtube.com/watch?v=b9UZ6_OCTaY has been set to private permissions to limit exposure. This video is a resource for understanding the security challenges associated with these vulnerabilities and ACAP, which occurred starting on **version 2.0** due to new development approaches and priorities. + + For ACAP Maintainers or developers interested in exploring the content, please contact the current active ACAP Maintainer(s) for an invitation to access the video. Engaging with this material can provide insights into the security considerations that have been acknowledged and inform future enhancements to the system's security measures. + 3. **Crop recommendations data integrity:** Ensuring that data presentations in PDF bulletins remain unaltered, trustworthy, and accurate is crucial for users and future developers. This priority stems from the concerns identified in items 1 and 2. 4. **Firestore database pollution:** Also related to item 1, the new **"Support Services"** data with insufficient validation, if pushed through the [Firestore REST APIs](https://cloud.google.com/firestore/docs/reference/rest/), can potentially allow writing unlimited key-value pairs with unlimited text or Object content length in Firestore Documents or creating Collections/Documents recursively outside the developer's intended schema or structure. If left unchecked, this can speed up the consumption of the Firebase standard plan quota (or drive up the billing if subscribed to the Firebase Blaze plan) in the long run. -> These issues, raised during the early 2.0 development phase, have been communicated to the new main ACAP code Maintainer, who is also the new primary developer/programmer leading the creation and enhancement of new features for Version 2.0. The new code Maintainer has made thoughtful decisions for balancing development speed with feature delivery, reflecting their understanding of the project's scope and the perceived security needs. They are open to addressing these issues as time and priorities allow within the ACAP project timeline. +> These issues, raised during the early 2.0 development phase (June 2024), have been communicated to the new main ACAP code Maintainer, who is also the new primary developer/programmer leading the creation and enhancement of new features for Version 2.0. The new code Maintainer has made thoughtful decisions for balancing development speed with feature delivery, reflecting their understanding of the project's scope and the perceived security needs. They are open to addressing these issues as time and priorities allow within the ACAP project timeline.
diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index 12280d0d..6326e0ad 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -1,6 +1,6 @@ import { Callout } from 'nextra/components' -# Welcome to ACAP Tutorials +# Welcome to ACAP Tutorials 🏡 This site offers a more organized and structured approach to documenting the software development approaches for the Agro-Climatic Advisory Portal - Bicol (ACAP Bicol), initially released as [ACAP 1.0](/changelog/#version-1-acap-10) at the end of 2022 and now enhanced to version [2.0](https://acap-bicol.github.io/) as of 2024. diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 2b74b2b7..32e32c41 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -4,7 +4,7 @@ import { Cards, Card, Callout } from 'nextra/components' ### Introduction -This series of tutorials describes how to run ACAP-Bicol (ACAP version 2.0) on localhost, using values for a new Region, using the initial ACAP 2.0 release version **`v10.1.0-alpha.1`**, dev branch @commit **`5c92235b`**. +This series of tutorials describes how to run ACAP-Bicol (ACAP version 2.0) on localhost, using values for a new Region, using the initial ACAP 2.0 release version **`v10.1.0-alpha.1`**, dev branch @commit **`c92235b`**. Fork the repository to receive the latest updates and bug fixes. Configure the following components to run ACAP for your PC or laptop for localhost development. @@ -48,4 +48,17 @@ If you are working on a forked repository behind several updates from the parent Project Maintainers occasionally update the parent repository **acap-v2** for maintenance, bug fixes, and minor/optional updates. _Sometimes, massive new feature updates_. Of the three (3) repository syncing options mentioned, doing the first or second options ensures up-to-date sync with the latest updates and bug fixes. - \ No newline at end of file + + + + +All updates and fixes should be from the (parent) **acap-v2** repository's (default) **`dev`** branch. Updates to the **acap-v2** `dev` branch expect to have been tested and ensured compatibility by the main ACAP code Maintainer(s) before committing new updates and fixes to the `dev` branch. + + + +### Questions and Inquiries + +- Concerns, questions, and inquiries with ACAP go through the mode of communication channel elected within ACAP (the ACAP FB Group Messenger). + > This communication channel is reserved only for the "active" and "official" ACAP members group. +- Alternatively, developers may create tickets (**GitHub Issues**) [within the (parent) **acap-v2** repository](https://github.com/amia-cis/acap-v2/issues) to describe their concerns in more detail. This page also contains code-related information about past inquiries and bug fixes that may be useful to other regions. + > The main ACAP code Maintainers ("active" and "inactive") may respond to these tickets within their available time. diff --git a/docs/pages/post-installation/cropping-calendar/calendar-v2.mdx b/docs/pages/post-installation/cropping-calendar/calendar-v2.mdx index b44ec57f..a8b4397d 100644 --- a/docs/pages/post-installation/cropping-calendar/calendar-v2.mdx +++ b/docs/pages/post-installation/cropping-calendar/calendar-v2.mdx @@ -19,7 +19,7 @@ The latest updates for **ACAP 2.1**, starting with @commit **95a97cd** in the ** > These Cropping Calendars are only compatible up to @commit **ee49568** in the **acap-v2 dev** branch. -Kindly chat the ACAP group chat for more information about the new Cropping Calendar Excel file for ACAP 2.1. +Kindly chat the ACAP group chat for more information about the new Cropping Calendar Excel file for ACAP 2.1. Alternatively, you may use the _[temporary workaround](https://github.com/amia-cis/acap-v2/issues/55#issuecomment-2485494426)_ until a final update to ACAP's _[ongoing items](https://github.com/amia-cis/acap-v2/issues/57)_ becomes available. ACAP 2.0 uses cropping calendars with _**two (2) groups/rows of crop stages**_ for each municipality supporting _**one (1) or more types of crops**_. View its raw EXCEL data files in the `/server/src/scripts/data/dataset_v2.0` directory for more information about its contents and data structure. diff --git a/docs/pages/post-installation/recommendations/recommendations-v2.mdx b/docs/pages/post-installation/recommendations/recommendations-v2.mdx index 6d02c08a..f9afce7a 100644 --- a/docs/pages/post-installation/recommendations/recommendations-v2.mdx +++ b/docs/pages/post-installation/recommendations/recommendations-v2.mdx @@ -17,7 +17,7 @@ The latest updates for **ACAP 2.1**, starting with @commit **95a97cd** in the ** > These Crop Recommendations are only compatible up to @commit **ee49568** in the **acap-v2 dev** branch. -Kindly chat the ACAP group chat for more information about the new Crop Recommendations Excel file for ACAP 2.1. +Kindly chat the ACAP group chat for more information about the new Crop Recommendations Excel file for ACAP 2.1. Alternatively, you may use the _[temporary workaround](https://github.com/amia-cis/acap-v2/issues/55#issuecomment-2485494426)_ until a final update to ACAP's _[ongoing items](https://github.com/amia-cis/acap-v2/issues/57)_ becomes available. ACAP 2.0 uses recommendations data similar to the ACAP 1.0 raw data, added with climate risk information and exclusion of several Excel columns. View its raw EXCEL data files in the `/server/src/scripts/data/dataset_v2.0` directory to gain insight into its new contents and data structure. diff --git a/docs/pages/requirements.mdx b/docs/pages/requirements.mdx index a5ee5d59..986c87f2 100644 --- a/docs/pages/requirements.mdx +++ b/docs/pages/requirements.mdx @@ -47,10 +47,11 @@ This post describes the dependencies and requirements needed to run run ACAP 1.0 5. Firebase - Firebase for Web - Firebase for NodeJS (Firebase Admin) - - Firebase Services - - Authentication - - Firestore - - Storage + - Firebase Services (Components) + - Authentication [[1]](https://firebase.google.com/docs/auth/) + - Firestore [[2]](https://firebase.google.com/docs/firestore/) + - Storage [[3]](https://firebase.google.com/docs/storage/) + - Hosting [[4]](https://firebase.google.com/docs/hosting/) _(Only used with the **development** environment)_ ### Cloud Service Accounts (standard pricing) @@ -58,7 +59,8 @@ This post describes the dependencies and requirements needed to run run ACAP 1.0 - https://github.com 2. Render (2) - https://render.com -3. Firebase (1) account +3. Firebase (2) accounts + - Separate [Firebase accounts](https://www.youtube.com/watch?v=CgN--jl_zJ0) to use with the **development** and **production** environments - https://firebase.google.com 4. Semaphore - https://semaphore.co diff --git a/docs/pages/showcase.mdx b/docs/pages/showcase.mdx index 8be2fdbc..1bb85a23 100644 --- a/docs/pages/showcase.mdx +++ b/docs/pages/showcase.mdx @@ -1,3 +1,3 @@ -# Showcase +# Showcase 🎨 _(content for this section is under construction)_ diff --git a/docs/pages/video.mdx b/docs/pages/video.mdx index dd0de9e1..ef1ac63a 100644 --- a/docs/pages/video.mdx +++ b/docs/pages/video.mdx @@ -1,6 +1,6 @@ import { Callout } from 'nextra/components' -# ACAP Video Tutorials +# ACAP Video Tutorials ▶️ ## Introduction