Skip to main content

Quickstart

1. Cloning the Repository​

You can clone the repository here https://github.com/csitgovsg-acube/attribution-api-v2

git clone https://github.com/csitgovsg-acube/attribution-api-v2.git

2. Building the containers​

You can skip this step, and pull the images instead in the next step to start the containers.

Pre-requisites​

These files are present in the images built to pull from, but missing in the repository itself. Please request for it if you plan to build it locally from the repository.

FESTIVE Model​

There are instructions in the README.md files.

model.uxc (festive-app)​

You need this file for the model to work. You can follow the README.md or git-lfs pull to retrieve the model file.

keys.toml (festive-store)​

The festive-store container requires configuration to access its endpoints. You can follow the README.md to set it up based on the given keys.EXAMPLE.toml file.

Building​

If you cloned the repository and planned to build the containers locally, there are two types of docker compose files; one is meant for development, and the other for staging / production. docker-compose-dev.yaml exposes all the ports and is only used in development for easier debugging.

environmentDocker ComposeDescription
.envdocker-compose.stg.yamlFor attribution engine in stg / prod
nildocker-compose-festive.stg.yamlFor FESTIVE model in stg / prod
.env.exampledocker-compose-dev.yamlIncludes both attribution engine & FESTIVE model
nildocker-compose.override.yamlFor FESTIVE model in dev
nildocker-compose.yamlOriginal FESTIVE compose file, in dev

Use --build arg in command to always rebuild from source

docker compose -f docker-compose-dev.yaml up -d --build
caution

The database credentials are hardcoded in the docker-compose-dev.yaml file. While it is okay for development, please do not use the docker-compose-dev.yaml file in production.

3. Starting the containers​

Pre-requisites​

These files are not part of the image but are required for the containers to start properly. These files are not present in the repository and are required to run docker compose or the containers. Please request for it if you cannot attain it.

Attribution Engine​

.env​

There are configurations inside this file that the services rely on. The containers will crash if it cannot find the configurations. You can follow .env.example to recreate this file. It should be in the same directory as your Attribution Engine docker compose file.

compose file (docker-compose.stg.yaml)​

In the docker compose files for staging / production, uncomment the lines with image and comment the lines with build. Do this for each container. The reference image pulls an image from an online repository while build builds the image locally from source.

Eg. uncommenting image, comment or remove build

image: ghcr.io/csitgovsg-acube/attribution-api:2.4.8
#build: ./attribution_api

Likewise, uncomment the volume references of postgres, rabbitmq and redis in Attribution Engine.

Eg. uncommenting named volume mounts

volumes:
  postgres:
    name: "attri-postgres-data"
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: "/opt/AttriAPIv2/data/pgdata"

  rabbitmq:
    ...

  redis:
    ...

FESTIVE​

backup (festive-postgres / festive-weaviate)​

The model will raise an error if it does not have any existing functions (imported from backup file) in its festive-postgres and festive-weaviate databases. You will need a copy of the backup file (.zip) as well.

  1. Create an environment

You can create an environment in Conda with the poetry package.

conda create -n festive poetry
  1. Install the FESTIVE library

Install the custom library with scripts to import backups to the database

poetry install
  1. Run the script to backup the functions
festive database restore --backup-file xxx.zip --host 127.0.0.1 --port 42420 --api-key "store-secret-key-you-set"
compose file (docker-compose-festive.stg.yaml)​

Uncomment the volume references of backups-data, postgres-data and weaviate-data in FESTIVE.

Eg. uncommenting named volume mounts

volumes:
  backups-data:
    name: "festive-backups-data"
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: "/opt/AttriAPIv2/data/backupsdata"

  postgres-data:
    ...

  weaviate-data:
    ...

Starting​

docker-compose.stg.yaml and docker-compose-festive.stg.yaml should pull the images from ghrc instead of building it locally.

Use these commands to bring the systems up

docker compose -f docker-compose.stg.yaml up -d
docker compose -f docker-compose-festive.stg.yaml up -d