Guide to Docker

Prerequisites

Docker and Docker-compose installed (Docker Engine on Windows and Mac will have both cli installed, while Linux users will need to download them separately)
For Windows users only:
- Virtualization needs to be enabled
- WSL2 backend needs to be installed
- More info can be found here
- WSL2 installation guide from medium
PGAdmin4 GUI to view database data
A local fork of the appropriate Lucky Parking branch
- dev for developers
- citation-analysis for data science
Create a db-backups directory in root of the lucky parking branch (master, dev, or citation-analysis) and download the SQL restore script from the google drive into the newly created directory (Lucky Parking Drive / psql-backups / lp-db-dev.sql)
Create a .env file in the root with the proper credentials and config (ask someone from the team to get this)

Setting up Docker

Docker is the recommended approach to quickly getting started with local development. Docker helps create a local/offline environment of almost anything (source code, database, etc) on your computer.

The recommended installation method for your operating system can be found here.

For both Windows and Mac, the Docker Engine installs both the Docker and Docker-compose CLI. For Linux, docker-compose is downloaded separately. Installation for docker-compose for linux can be found here.

More on using Docker and the concepts of containerization:

Get started with Docker

Installing WSL2 on windows:

https://docs.microsoft.com/en-us/windows/wsl/install-win10

Alternatively, follow this guide for enabling virtualization and installing WSL2 on windows:

https://s1gr1d.medium.com/how-to-set-up-linux-on-windows-with-wsl-2-debe2a64d20d

Docker for developers

For developers, we use docker to replicate the backend environment locally/offline. This allows developers to work using the same environment, and avoid having to setup the database (via downloads, or sshing into an instance hosting it).

It should be noted that both production and staging environment do not use docker, and developers will only use docker for their local environment.

The docker-compose file for developers create a Node.js container and a PostgreSQL database container. The database container uses a SQL script to restore a copy of the database.

The Node.js container is based on the node:16-alpine image. This is a lightweight image that uses less memory and space, and has better performance, security and maintainability.

The PostgreSQL container is based on the PostGIS image. This provides the base PostgreSQL image with PostGIS extensions installed.

Setup

Ensure the current branch has the latest updates from upstream
Go to root of the Lucky Parking source code directory
Create a new directory called db-backups. This directory is part of the .gitignore file.
Download the current available SQL database restore script into the newly created db-backups directory from the Lucky Parking admin drive.
- Lucky Parking Drive >> Lucky Parking Folder >> psql-backups >> lp-db-dev.sql
Go to the server directory

cd server

There should be a docker-compose.yml file.
- If you look inside the file, you should see the following line: - ../db-backups/lp-db-dev.sql:/docker-entrypoint-initdb.d/lp-db-dev.sql
- This tells Docker to look into the db-backups directory and run the SQL script on build. This essentially restores a backup of the database into the container.
In the same directory, there should be a .env file
- If not, create one and get the proper variables from a team member
- This .env file is part of .gitignore
Run docker to launch the container

docker-compose up --build

This launches a container with the following services: Node.js and PostgreSQL db
The node container mirrors the code files under the server directory. Any updated files will be replicated instantly on the docker container
Once the PostgreSQL db is recreated, the node container will listen to it on port 5432
- You may see the node container fail to connect during the database restore process. It will reconnect at the end of that process.

Once you are finished using the container, stop it

docker-compose down

This spins down the container, available to be used the next time you spin it up.
It keeps the created volume, so any updates to the database will be kept.
Alternatively, you can run docker-compose down -v to delete the volume after stopping the container. This ensures that on the next startup, docker will rebuild the database based on the SQL script again, and any changes to the db before will be lost.

Docker for data science

This part is currently WIP because the docker for data science is currently incomplete

The docker-compose file for the data science team creates a PostgreSQL database container. The database container uses a SQL script to restore a copy of the database.

The PostgreSQL container is based on the PostGIS image. This provides the base PostgreSQL image with PostGIS extensions installed.

Setup

Ensure the current branch has the latest updates from upstream
Go to root of the Lucky Parking source code directory under the citation-analysis branch
Create a new directory called db-backups. This directory is part of the .gitignore file.
Download the current available SQL database restore script into the newly created db-backups directory from the Lucky Parking admin drive.
- Lucky Parking Drive >> Lucky Parking Folder >> psql-backups >> lp-db-dev.sql
While still in the root directory, check to see that there is a docker-compose.yml file.
- If you look inside the file, you should see the following line: - ./db-backups/lp-db-dev.sql:/docker-entrypoint-initdb.d/lp-db-dev.sql
- This tells Docker to look into the db-backups directory and run the SQL script on build. This essentially restores a backup of the database into the container.
In the same root directory, there should be a .env file
- If not, create one and get the proper variables from a team member
- This .env file is part of .gitignore
Open the terminal on the root Lucky Parking directory and run the following command to launch the container:

docker-compose up --build

This launches a container with the following services: PostgreSQL db

Once you are finished using the container, run the following command to stop it:

docker-compose down

This spins down the container, available to be used the next time you spin it up.
It keeps the created volume, so any updates to the database will be kept.
Alternatively, you can run docker-compose down -v to delete the volume after stopping the container. This ensures that on the next startup, docker will rebuild the database based on the SQL script again, and any changes to the db before will be lost.

Common Docker and Docker-compose commands:

Note: For linux users, docker and docker-compose needs to be preceded with sudo

docker-compose up --build
- Docker will look for a docker-compose file in the current directory and run it. It will build a new container if it doesn't exist yet.
docker-compose down
- Stop the currently running container based on the docker-compose file in the current directory.
docker-compose down -v
- Same as #2, but any associated volumes will also be deleted. On the next build, the volume will be recreated from scratch.
docker volume ls
- Lists the current volumes created by docker.
docker volume prune
- Prunes any orphaned volume. An orphaned volume is a volume that is not attached to any container.
docker image ls
- Lists the current images downloaded by docker.
docker image prune
- Prunes any orphaned images. Whenever docker-compose builds a new container, it also creates an associated image with it. It is a good idea to prune these once in a while.
docker container ls
- Lists the containers created by docker.
docker container prune
- Prunes any orphaned containers.
docker ps -a
- Show currently running containers.
docker kill $(docker ps -a)
- Kill all running containers.