Follow these steps to setup a local development environment.

This software should be installed on your machine to develop on this project.

Download and install Docker Desktop. It's the only required software.

This repo sets up a Node JS virtual machine using Docker Compose. However, it may be convenient to install Node JS on your local machine anyway. I recommend using NVM to manage Node JS versions. This repo contains an .nvmrc file and if you follow the NVM setup instructions, especially the section on shell integration you can make NVM switch to the right Node version based on the .nvmrc file automatically whenever you change directories to this project.

This is optional, but I highly recommend Visual Studio Code. It works very well and it's what I used to develop on this project myself.

Make sure you have the prerequisites installed.

Copy example.env to .env and make sure you are ok with it's contents.

Run this command from the project folder to start a development environment:

docker compose up -d

This will download and install NGINX and MariaDB. You can also select another database.

After startup, you can setup SSL and then connect your browser to https://cc.localhost.

On first run, the proxy/setup.js script will generate a bunch of SSL certificate files in proxy/certs:

• ca.crt
• ca.key
• ca.pem
• ca.srl
• cc.localhost.crt
• cc.localhost.csr
• cc.localhost.ext
• cc.localhost.key

The setup script will generate the *.localhost.* files based on the NAME environment variable configured in .env. You can also directly control the domain name for the project by editing proxy/domains.template. Check the logs of the web docker container for details.

The ca.* files are actually a self-signed certificate authority that is in turn used to sign the domain certificates. Double-click ca.crt to install the certificate authority as a trusted authority on your machine, to make your browser trust your self-signed certificates.

Once you have added the certificate authority and restarted your browser, you should be able to visit https://cc.localhost with a trusted SSL certificate.

To stop the dev environment, run

docker compose down

This repo actually comes with compose.yml files for 3 different databases:

• MariaDB (in db/mariadb)
• MySQL (in db/mysql)
• PostgreSQL (in db/postgres)

To select which database to use, set the environment variable DB_TYPE in .env to one of mariadb, mysql or postgres. More details in .env.