acaptutorials.github.io

ACAP Bicol (ACAP 2.0) development documentation.

Built with Nextra, a modern static site generation framework running on NextJS.

Important

This project uses Nextra version 2.

Requirements

The following dependencies are used for this project. Feel free to experiment using other dependencies and versions.

1. Windows 10 64-bit OS
2. nvm version 1.1.12 (for Windows)
3. NodeJS LTS v20.15.0
   • (installed using nvm)
   • node v20.15.0
   • npm 10.7.0

Core Libraries and Frameworks

The app depends these libraries and frameworks.

• NextJS v14.2.5
• Nextra v2.13.4 [v2]
• nextra-theme-docs v2.13.4
• React v18.3.1
• TailwindCSS v3.4.7

Table of Contents

• Requirements
• Installation
• Usage
  • General Usage
  • Uploading and Referencing Images from /assets
• Available Scripts
• Usage with Docker
  • Use Pre-Built Development Docker Image
  • Build the Development Docker Image
• Usage with GitHub Actions
• Deployment to Docker Hub

Installation

1. Clone this repository.
   git clone https://github.com/acaptutorials/acaptutorials.github.io.git

2. Install dependencies.
   

   cd docs
   npm install
   

3. Set up the environment variables. Create a .env file inside the /docs directory with reference to the .env.example file.

   Variable Name	Description
   RELEASE_VERSION	Latest respository Release (Tag) number
   RELEASE_PAGE	Latest GitHub release page
   COMMIT_ID	Default branch's commit sha related to the RELEASE_VERSION
   OPENGRAPH_IMAGE_URL	URL of a 1200x630 image to be used as an OpenGraph thumbnail
   BASE_URL	The base URL for the frontend of the documentation website.
   WATCHPACK_POLLING	Enables hot reload on NextJS apps running inside Docker containers on a Windows host. Set it to true if running Docker Desktop with WSL2 on a Windows OS.

Usage

General Usage

1. Run the app for local dedvelopment with:
   

   cd docs
   npm run dev
   

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 build
   
   # 2.2. Create and start the development client and server containers
   docker compose up
   
   # 2.3. Stop and remove the development containers, networks, images and volumes
   docker compose down
   

3. Add or edit MDX files in the /pages directory, or add React components in the /components directory.

   • View the nextra (docs-theme) documentation for more information on using nextra to add content.

Uploading and Referencing Images from /assets

To display a new image:

1. Upload the image to the /assets branch, (Issue #102)

   • Commit the file under the appropriate directory (e.g., /images/, /docs/, etc.).

   • Use unique, versioned file names (e.g., feature-v2.png) to prevent caching issues.

     ⚠️ NOTE: Overwriting an existing file with a new version will not immediately update in browsers due to GitHub's CDN caching.

2. Get the raw URL:

   • Open the file in GitHub, click View Raw, and copy the URL.
   • The URL will look like this:
     https://raw.githubusercontent.com/acaptutorials/acaptutorials.github.io/assets/<path-to-file>

3. Use the raw URL in Markdown or HTML:

   Markdown
   ![New Picture](https://raw.githubusercontent.com/acaptutorials/acaptutorials.github.io/assets/images/example.png)

   HTML
   <img src="https://raw.githubusercontent.com/acaptutorials/acaptutorials.github.io/assets/images/example.png" alt="New Picture" />

Best Practices

• Use descriptive file names and organize assets into logical folders.
• Compress or optimize images before upload to keep repository size manageable.
• Always try to update references when renaming or versioning files.

Available Scripts

npm run dev

Starts the local NextJS / Nextra app in development mode on localhost.

npm run build

Builds the static site into the "out" directory.

npm run lint

Checks lint errors.

npm run lint:fix

Fixes lint errors.

Usage with Docker

Usage with Docker is an alternate option to using Node directly from the Usage section.

Use Pre-Built Development Docker Image

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 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 - step # 2 for more information.

3. Run the development Docker image.
   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

Build the Development Docker Image

1. Build the development Docker image on your machine.
   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 - step # 2 for more information.

3. Run the development Docker image.
   docker compose up

Usage with GitHub Actions

1. Add the environment variables described in the Installation - step # 2 section to GitHub Secrets.
2. Create a Release to deploy the site to the production environment (GitHub Pages).
3. To update the banner content while there are no code or content updates:
   • Update the GitHub Secrets: RELEASE_VERSION, COMMIT_ID and RELEASE_PAGE
   • Re-deploy the latest production environment workflow from the GitHub Actions tab.

Deployment to Docker Hub

This repository deploys the latest development Docker image acaptutorials/acaptutorials.github.io:latest to Docker Hub on the creation of new Tags/Releases with GitHub Actions. Supply the following GitHub Secrets and Variable to enable deployment to Docker Hub. It requires a Docker Hub account.

The Docker Hub image is available at:

https://hub.docker.com/r/acaptutorials/acaptutorials.github.io

GitHub Secrets

GitHub Secret	Description
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

GitHub Variable	Description
DOCKERHUB_USERNAME	Docker Hub username

@acaptutorials
20240806
20250901