Table of Contents

• Want to contribute?
• Setup
  • Linux
  • Windows
  • .env
  • Seed the database
• Running Locally
• Deployment
  • Setup Docker Environment
  • Build the Base-Layer Image
  • Working With Docker
    • docker-compose
    • supervisord
    • Switching to debug mode

---

Setup

(This assumes you have Python installed)

1. Download or Clone this repository.
2. Open terminal (Linux) / powershell (Windows) and cd to the directory of the project.

# Linux
cd /path/to/traveller-lite

# Windows
cd C:\path\to\traveller-lite

---

Setup / Linux

Create a virtual environment and activate it.

python3 -m venv venv

source venv/bin/activate

Install the requirements.

pip install -r requirements.txt

---

Setup / Windows

Create a virtual environment and activate it.

python -m venv venv

.\venv\Scripts\activate

Install the requirements.

pip install -r requirements/main.txt

---

Setup / .env

Copy the included .env.example file and rename it to .env, this file contains the environment variables that the app needs to run.

Change the values to suit your local environment.

Here's an example:

Note: It is important to set both the SUPER_ADMIN_ACCOUNT and SUPER_ADMIN_PASSWORD before using the seed CLI command.

The email address used for the SUPER_ADMIN_ACCOUNT doesn't need to be a real email address. [email protected] is fine.

Note: When in development mode, make sure the EMAIL_DEV_MODE is set to 1. This will prevent the app from trying to send emails.

# SECRET_KEY is passed to Flask.config['SECRET_KEY']
SECRET_KEY=flaskcon

# The following are used for sending emails, 
# see app/extensions/__init__.py & app/utilities/email_service.py
EMAIL_DEV_MODE=1
EMAIL_USERNAME=none
EMAIL_PASSWORD=none
EMAIL_SERVER=none
EMAIL_PORT=0

# The email address that all proposal correspondence should be discussed
# This email address will be used to to inform the submitter to contact this
# email address for any questions or concerns.
FLASKCON_EMAIL_ADDRESS=none

# Super admin account details that will be used in the CLI
# command 'flask seed'
SUPER_ADMIN_ACCOUNT=none
SUPER_ADMIN_PASSWORD=none

# Used to populate the docker.config.toml file when using
# a postgres Docker deployment.
POSTGRES_USER=postgres
POSTGRES_PASSWORD=none
POSTGRES_DB=flaskcon
POSTGRES_PORT=5432
POSTGRES_LOCATION=localhost

Account confirmation and Password reset links that would usually be emailed will appear in the terminal

---

Setup / Seed the database

Run the following command to seed the database with the starting data, and create the admin account.

flask seed

---

Running Locally

Flask

flask run

Debug

flask run --debug

Run with gunicorn

Note: gunicorn will get run conditions from gunicorn.config.py

gunicorn -c configs/gunicorn.config.py

IMPORTANT:

• gunicorn will not work under Windows, use WSL or a Linux VM.

Huey

Huey is used as a task queue, it is used to send emails asynchronously. You will need to run the consumer in a separate terminal.

huey_consumer app.huey.run

---

Deployment

Docker is used for deployments, make sure you have Docker installed.

Deployment / Setup Docker Environment

Note: Instructions are for a debian based distro. The instructions below also work for Windows Subsystem for Linux (WSL) Ubuntu.

sudo apt update

sudo apt install curl

sudo apt install git

curl -fsSL https://get.docker.com/ | sh

sudo groupadd docker

sudo usermod -aG docker $USER

Important: You will need to log out and log back in for the group changes to take effect. Or restart to be sure.

Navigate to a folder of your choice and clone the repository.

sudo git clone [email protected]:FlaskCon/traveller-lite.git

---

Deployment / Build the Base-Layer Image

cd traveller-lite

docker build -t flaskcon/base-layer -f Dockerfile-base-layer .

---

Deployment / Working With Docker

There is a choice of different docker-compose files.

docker-compose.yml is the default, and will run the app with a postgres database.

docker-compose-sqlite.yaml will run the app with a sqlite database.

docker-compose-sqlite-dev.yaml will run the app with a sqlite database, but run Flask in debug mode. This will also attach the app/ folder to the container, so changes to the code will be reflected in the app.

Note: Each database has persistent storage, so you can stop and start the containers without losing data.

important: The containers are set up to use the host network, so the app will be accessible on the host's IP.

---

... / Working With Docker / docker-compose

Starting the containers

Working from the location of the cloned repository, run the following command:

docker-compose -f <COMPOSE FILE CHOICE> up --build -d

or

docker-compose up --build -d

to use the default docker-compose.yml file.

-f will allow you to choose which docker-compose file to use.

--build will instruct docker-compose to rebuild the image.

-d will run the containers in the background.

The name of the container will be traveller-lite, this is pulled from the container_name in the docker-compose file.

Stopping the containers

docker-compose -f <COMPOSE FILE CHOICE> down

---

... / Working With Docker / supervisord

Supervisor is used to control the app as a service. This allows the Docker container to be stopped and started without

The following command will allow you to access the container's terminal.

docker exec -it traveller-lite /bin/sh

You can then use the following commands to manage the app.

Show the status of the app

supervisorctl status

Stop the app

supervisorctl stop traveller-lite

Start the app

supervisorctl start traveller-lite

Restart the app

supervisorctl restart traveller-lite

... / Working With Docker / Switching to debug mode

supervisorctl stop traveller-lite

flask run --host=0.0.0.0 --debug

ctl+c to stop the app.

supervisorctl start traveller-lite

---

Production Commands

Pull the latest changes from the repository and rebuild the containers

cd /var/www/flask/traveller-lite

git pull && docker-compose up --build -d