Getting Started

The following page guides you step by step to setup and run ListOf in a local development environment. For a deployment to production, follow the same steps and then refer to the page Production Deployment.

• Requirements
  • Linux
  • Windows
• Setup Your Instance
• Run Your Instance

Requirements

ListOf has been fully containerized with Docker to ensure easy deployment and portability. Follow the steps below to install Docker and Docker Compose on your machine.

Linux

Install Docker

Add the Docker repository to your Linux machine, execute the following commands in a terminal window.

$ sudo apt-get update
$ sudo apt-get install apt-transport-https ca-certificates curl software-properties-common
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

Install Docker Community Edition.

$ sudo apt-get update
$ sudo apt-get install docker-ce

Add your user to the docker group to setup its permissions. Make sure to restart your machine after executing this command.

$ sudo usermod -a -G docker <username>

Install Docker Compose

Execute the following command in a terminal window.

$ sudo apt install docker-compose

Once the installation is complete, proceed to the following step: Setup Your Instance

Windows

• If your computer runs on Windows Pro, install Docker Desktop for Windows.
• If your computer runs on Windows Home, install Docker Toolbox for Windows.

Install Docker Desktop for Windows (Windows Pro)

Install Docker Community Edition for Windows from the following the URL: Docker Desktop for Windows. Once the installation is complete, proceed to the following step: Setup Your Instance

Install Docker Toolbox for Windows (Windows Home)

Install Docker Toolbox for Windows from the following the URL: Docker Toolbox for Windows. Once the installation is complete, proceed to the following step: Setup Your Instance

Using Docker Toolbox default settings requires the project to be in the directory: C:/Users/<your_user>/

Setup Your Instance

Create Configuration File

Create a text file named .env at the root of the repository using the template below. This file is used by Docker Compose to load configuration parameters into environment variables. Make sure to update the postgres user password for both POSTGRES_PASSWORD and DATABASE_URL parameters as well as the GraphQL API SECRET_KEY.

# DB
# Parameters used by listof-db container
POSTGRES_DB=listof
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change_me

# GRAPHQL
# Parameters used by listof-graphql container
DATABASE_URL=postgres://postgres:change_me@db:5432/listof
SECRET_KEY=change_me

Create SSL Certificate

The GraphQL API and the web app are served by an Nginx web server with SSL encryption (https). In order to encrypt http requests when running the project locally, you must generate a self-signed certificate and its corresponding private key. You can do it using this docker container: https://github.com/alexisrolland/docker-openssl

Execute the following commands to build the Docker image:

# Clone repository
$ git clone https://github.com/alexisrolland/docker-openssl.git
$ cd docker-openssl

# Build Docker image
$ docker build -t docker-openssl:latest .

Run the container in interactive mode. Note the files cert.pem and key.pem must be created in the ListOf project folder: ...\your_path\listof\nginx\config:

# Replace <your_path> with your base folder path
# This is where cert.pem and key.pem files will be created

# If you are on Linux
$ docker run -it --rm -v "/your_path/listof/nginx/config:/openssl-certs" docker-openssl

# If you are on Windows Pro
$ docker run -it --rm -v "C:\your_path\listof\nginx\config:/openssl-certs" docker-openssl

# If you are on Windows Home
$ docker run -it --rm -v "/c/your_path/listof/nginx/config:/openssl-certs" docker-openssl

Generate the certificate file and its private key:

# Generate cert.pem and key.pem files
$ req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365

You will be prompted a couple of questions which you can answer following this example:

Country Name (2 letter code) [AU]:CN
State or Province Name (full name) [Some-State]:Shanghai
Locality Name (eg, city) []:Shanghai
Organization Name (eg, company) [Internet Widgits Pty Ltd]:ListOf
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:localhost
Email Address []:

Build Docker Images

Go to the project root and execute the following command in your terminal window.

$ cd listof
$ docker-compose build --no-cache

Run Your Instance

Run Docker Containers

To start all the Docker containers in Development mode, go to the project root and execute the following command in your terminal window. To run Docker containers in Production mode, refer to the page Production Deployment.

$ cd listof
$ docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

Individual components can be accessed at the following addresses:

Component	Docker on Linux / Windows Pro	Docker on Windows Home
Web application	https://localhost	https://192.168.99.100
GraphQL API Documentation	https://localhost/graphiql	https://192.168.99.100/graphiql
PostgreSQL Database	host: localhost, port: 5432	host: 192.168.99.100, port: 5432

You can connect to the application for the first time with the default admin user. Make sure you change its password!

• Login: admin
• Password: admin