Skip to content

Deploying JAMS Locally for Dev

Jump to bottom
James Dougan edited this page May 21, 2025 · 13 revisions

This guide will explain how to deploy JAMS locally for development purposes Note, this guide is to be used with the develop branch

Deploy a DB, S3 Bucket and Redis

First you need to deploy a DB. JAMS is built to use PostgreSQL, so use that. You will also need some form of S3 bucket storage. I will be using MinIO. Finally you will need an instance of Redis.

Tools used:

You can deploy these however you want to, but I will be using docker to have it easily destroyed and recreated when needed. If using docker, you can use this compose file:

services:
  jams-dev-db:
    image: postgres:13
    container_name: jams-dev-db
    ports:
      - 5432:5432
    environment:
      POSTGRES_USER: jams
      POSTGRES_PASSWORD: jams
      POSTGRES_DB: jams-main
    volumes:
      - /path/to/db:/var/lib/postgresql/data
  jams-dev-minio:
    image: "minio/minio:latest"
    container_name: jams-dev-minio
    restart: unless-stopped
    command: minio server /mnt/data --console-address ":9001"
    ports:
     - 9000:9000
      - 9001:9001
    environment:
      - MINIO_ROOT_USER=jams
      - MINIO_ROOT_PASSWORD=jamsminiopassword
    volumes:
     - /path/to/minio_data:/mnt/data
  jams-dev-redis:
    image: redis:8
    container_name: jams-qa-redis
    restart: unless-stopped
    command: ["redis-server", "--requirepass", "jamsredispassword"]
    ports:
      - "6379:6379"

The only thing you need to change is /path/to/db and path/to/minio_data. This will be somewhere on your filesystem to allow the db data to be persistently stored. Username and password are fine to stay as they are as this is only for development. But these should be changed in production.

Add the DB, MinIO, and Redis to a .env file

For the next steps, you need to go into the project directory in your terminal. This can be via the system terminal or your IDE's terminal.

cd /path/to/project

In order to locally run JAMS in your code editor, you need to define the endpoints of your DB, local S3 bucket and Redis servers.

You just need to add a .env file in the root of the project (same directory that README.md is in). You only need to add DATABASE_URL, MINIO_ENDPOINT and REDIS_URL. By default in the code, they are jams-db, jams-minio, and jams-redis respectively. This is because it can use the docker network to communicate. This needs changed to the host name of where the DB and MinIO server you deployed in the previous step is hosted. So if you deployed in on your local machine, you just need to use 127.0.0.1 as your hostname. The DB has a few extra bits in its path, but you only need to worry about the hostname. In this example, i will use 127.0.0.1:

DATABASE_URL=postgresql://jams:jams@127.0.0.1:5432/jams-main
MINIO_ENDPOINT=127.0.0.1:9000
REDIS_URL=redis://default:jamsredispassword@127.0.0.1:7379

For the Redis url, you just need to make sure that jamsredispassword matches the password you set in the previous step

Prepare your environment

Install Python packages If you haven't done already, create a python virtual environment with:

python3 -m venv venv

Then open it with: MacOS/Linux

source venv/bin/activate

Windows

.\venv\scripts\activate

Then you need to install the python libraries from the requirements.txt file. Run:

pip install -r requirements.txt

Install NodeJS packages First make sure you have NodeJS and NPM installed on your machine. You can follow this: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm

Once you have NodeJs and NPM installed, you can install the packages, using the following command:

npm i

Prepare the DB

Before you can run the app, you have to prepare the database and setup migrations.

NOTE: Make sure the DB is fully up and running before doing this step. The logs should say something along the lines of "database is ready to accept connections"

First we will initialise the database with all the tables and get it ready for its first "migration"

There is a script to simplify a lot of this. Run the following command from the root of the project:

./scripts/migrate_db.ps1

Choose option 1 to initialise the migrations folder.

Next we will create the first migration. This will be important for later. Run the .ps1 script again and this time choose option 2 to generate a migration script Finally, run the script one more time and choose option 3 to apply the migration to the db

At this point, the DB should be initialised and ready for use by our app. But before running the app, We will seed the database and add a few default entries like users. To do this, we need to run a few python commands inside flask.

First we need to open the flask shell in the server part of JAMS:

./scripts/dev_shell.ps1

Choose option 2 for server. This will open a shell inside flask where we can write line by line a short python program. Make sure to type each line correctly before hitting enter and going to the next line.

from server import create_app, seed_database
app = create_app()
seed_database(app)

Once that is done, you can exit the flask shell with quit()

Compile the applications Typescript files into JavaScript for web

This project uses typescript to write the frontend for type safety. However we browsers expect JavaScript. Before you can run the application, you have to compile the TypeScript into JavaScript.

To do this, run the following command:

npm run build

This will build the TS files into JS files and create mapping files so you can debug in the browser. This command will also sit open and watch for changes and then build them. So when you save a file, it will automatically build the changes for you.

Run the application

At this point, the database should be stood up, initialised, migrated, seeded with some default values and the Typescript converted to JavaScript. Now the only thing left to do is run the app.

First I would suggest to open another terminal tab so your Typescript build command can continue to be watching. To start the app, you can simply run:

python ./jams/run_dev.py

That should load up the app and you should be able to access it at 127.0.0.1:5000

Updating Database tables

If during your development you need to update the database to add new tables or columns and you don't want to destroy and rebuild the database, you can use the migration tool we set up earlier in this guide.

Once all your code changes are done and saved, you can run the same commands as before:

./scripts/migrate_db.ps1

This time you wont need to do option 1, as that is only used on the very first time. You only need to run options 2 (migrate) and 3 (upgrade) .

Then to re-seed the DB, open the flask shell

./scripts/dev_shell.ps1
2) Server

This will open a shell inside flask where we can write line by line a short python program. Make sure to type each line correctly before hitting enter and going to the next line.

from server import create_app, seed_database
app = create_app()
seed_database(app)

Once that is done, you can exit the flask shell with quit()

As long as your code is valid, this should update the DB with your new tables/columns.

Clone this wiki locally