LSCS Website

Development Setup Prerequisites

The softwares needed when developing this project for each OS and development setups of each OS are listed below.

MacOS or Linux

Local Setup

• Node.js v16 LTS (v16.20.0 Gallium) [Download] or nvm (node version manager) [Installation]
• Gridsome CLI [Installation]
• Yarn [Installation]

Dockerize Setup

• Docker Desktop [Download]

Windows

Local Setup without WSL 2 (Windows Subsystem for Linux v2)

• Node.js v16 LTS (v16.20.0 Gallium) [Download]
• Gridsome CLI [Installation]
• Yarn [Installation]

Local Setup with WSL 2 (Windows Subsystem for Linux v2)

• WSL 2 (Windows Subsystem for Linux v2) [Installation]

Install these softwares inside the WSL2 Linux distribution, preferably Ubuntu:

• Node.js v16 LTS (v16.20.0 Gallium) [Download] or nvm (node version manager) [Installation]
• Gridsome CLI [Installation]
• Yarn [Installation]

Dockerize Setup

• WSL 2 (Windows Subsystem for Linux v2) [Installation]
• Docker Desktop [Download]

Additional Notes

• For the Docker Setup in Windows, cloning of project can be done inside the Windows file system or inside the WSL 2 Linux distribution file system.
  • When project is cloned inside the Windows file system, hot reload won't work when running the development server of Gridsome. Though the port of the docker is exposed to your host machine, it is important to note that the Docker container is being ran as a process in the WSL 2 Linux distribution. Since it is running in WSL 2, any access to the windows file system is another network connection and the Gridsome development server is incapable of watching this network connection. (This issue is still open in their repository)
  • When project is cloned inside the WSL 2 Linux Distribution file system, there's a possiblity that the some or all the files in the project folder could either be lost or corrupted. To properly save and backup your changes, branch out from your current feature branch and name that branch as wip-<name-of-branched-out-feature-branch>, and then push it in the remote repository.
• In order to edit the files when the project folder is cloned inside the WSL2 Linux distribution, either terminal editors (e.g. nano, micro, VIM, neovim, etc.) or VS Code with WSL Extension.
• The WSL 2 Linux distribution has its own git. Unless, it is not preinstalled, then installation may be needed.
  • Since git is inside it, then your Git Credentials for Github is not saved in the system.
  • When using the HTTPS protocol for logging in to your GitHub account in the Linux terminal be sure to input your Personal Access Token (PAT) in the password field. (This is a new protocol by GitHub).
    • Guide on how to generate your Personal Access Token (PAT) [Guide]

Supplementary Knowledge and Materials

Here are some materials that could provide supplementary knowledge to the frameworks and softwares that are going to be used in the project.

Gridsome and Netlify CMS

• Netlify CMS - Content Management Systems (using Gridsome) [YouTube]
• Gridsome Docs [Documentation]

Docker

• Docker Crash Course Tutorial [YouTube]
• Docker Docs [Documentation]

WSL 2 (Windows Subsystem for Linux v2)

• WSL 2: Getting Started [YouTube]
• Manual Installation Steps for Older Versions of WSL [Installation]

Local Development

0. Install yarn package manager

npm install --global yarn

1. Clone the repository

# Clone the `LSCS_Website_CMS`
git clone <repository-https-clone-link>

# Move into the project directory
cd LSCS_Website_CMS

2. Install the dependencies

# Install dependencies
yarn install

3.a. Run development server

# Run Gridsome dev server
yarn dev

Access the website at http://localhost:8080

NOTE: This might not work especially for the latest releases of Node.js. Use Node.js v16 LTS as much as possible.

3.b. Build the project

# Generate static site inside the `dist` directory of the project
yarn build

Dockerize Development

1. Clone the repository

# Clone the `LSCS_Website_CMS`
git clone <repository-https-clone-link>

# Move into the project directory
cd LSCS_Website_CMS

2. Building Docker image

# Build the Docker image for desirable development environment,
# then create a container and start it.
yarn build:docker

Access the website at http://localhost:8080

NOTE: After building the image, it will create the dev container and run it. This will result in starting the Gridsome development server. Enter <Ctrl> + <c> to stop the development server and the container.

3. Starting deveopment container

# Start dev container using the built Docker image
yarn dev:docker

Access the website at http://localhost:8080

NOTE: Enter <Ctrl> + <c> to stop the development server and the container.

Resetting setup

# Clear/Delete the Docker image, container and  
# volumes created for the development enviroment
yarn docker-reset