Controlled Substance Licence (CSL)

Controlled Substance Licence (CSL) allows the public to register and apply for a license to handle controlled substances. The CSL includes a suite of four forms: Registration, Low THC Cannabis, Controlled Drugs, and Precursor Chemicals.

Description

• The form facilitates the upload of required documents, such as the company registration certificate, certificate of good conduct.
• The user is able to review all the answers provided to confirm their details prior to submission.

Getting Started

• Install & run locally
• Install & run locally with Docker Compose
• Install & run locally with VS Code Devcontainers

Dependencies

• This form is built using the HOF framework
• Gov.uk Notify to send notification emails
• File Vault to store and retrieve uploaded files

Install & Run the Application locally

Prerequisites

• Node.js >=20.20.2 <21.0.0
• Redis server running on default port 6379
• File Vault Service - running port 3000
• hof-rds-api Service - running port 5000 for service 'csl'

Setup

1. Create a .env file in the root directory and populate it with all the required environment variables for the project.
2. Install dependencies using the command yarn.
3. Start the service in development mode using yarn run start:dev.

Install & Run the Application locally with Docker Compose

You can containerise the application using Docker. The .devcontainer directory includes a docker-compose.dev.yml file for orchestrating multi-container application.

Prerequisites

• Docker

Setup

By following these steps, you should be able to install and run your application using a Docker Compose. This provides a consistent development environment across different machines and ensures that all required dependencies are available.

1. Make sure you have Docker installed and running on your machine. Docker is needed to create and manage your containers.

2. To configure your dev environment, copy /.devcontainer/devcontainer.env.sample to devcontainer.env in the same directory and fill in the necessary values. This ensures your development container is set up with the required environment variables.

3. Open a terminal, navigate to the project directory and run: docker compose -f .devcontainer/docker-compose.dev.yml up -d

4. Once the containers are built and started, you can go inside the app container: docker exec -it devcontainer-hof-csl-app-1 sh (note: Docker containers may be named differently)

5. Run the necessary commands to install dependencies yarn and yarn start:dev to start your application.

6. If you want to seed the postgres database with data specified in the CSL hof-rds-api service you can exec into the Docker container for hof-rds-api and run yarn db:seed. This should add some basic data to certain DB tables enabling basic functionality.

Install & Run the Application locally with VS Code Dev Containers

Alternatively, if you are using Visual Studio Code (VS Code), you can run the application with a VS Code Dev Containers.

The .devcontainer folder contains the necessary configuration files for the devcontainer.

Prerequisites

• Docker
• VS Code Dev Containers extention

Setup

By following these steps, you should be able to run your application using a devcontainer in VS Code. The Dev Containers extension lets you use a Docker container as a full-featured development environment. This provides a consistent development environment across different machines and ensures that all required dependencies are available. A devcontainer.json file in this project tells VS Code how to access (or create) a development container with a well-defined tool and runtime stack.

1. Make sure you have Docker installed and running on your machine. Docker is needed to create and manage your containers.

2. Install the Dev Containers extention in VS Code. This extension allows you to develop inside a containerised environment.

3. To configure your dev environment, copy /.devcontainer/devcontainer.env.sample to devcontainer.env in the same directory and fill in the necessary values. This ensures your development container is set up with the required environment variables.

4. Run the Dev Containers: Open Folder in Container... command from the Command Palette (F1) or click on the Remote Indicator (≶) in the status bar. This command will build and start the devcontainer based on the configuration files in the .devcontainer folder.

5. Once the devcontainer is built and started, you will be inside the containerised environment. You can now work on your project as if you were working locally, but with all the necessary dependencies and tools installed within the container.

6. To start the application, open a terminal within VS Code by going to View -> Terminal or by pressing Ctrl+backtick. In the terminal, navigate to the project directory if you're not already there.

7. Run the necessary commands to install dependencies yarn and yarn start:dev to start your application.

8. If you want to seed the postgres database with data specified in the CSL hof-rds-api service you can exec into the Docker container for hof-rds-api and run yarn db:seed. This should add some basic data to certain DB tables enabling basic functionality.

Testing

Linting Tests

$ yarn test:lint

Unit Tests

$ yarn test:unit

Deployment

This application is containerised and ready for deployment on Kubernetes. Refer to the kube/ directory for Kubernetes deployment scripts.

Redis persistent storage (Kubernetes)

Redis stores session/cache state under /var/lib/redis (see kube/redis/redis-deployment.yml). This repo now supports PVC-backed Redis storage so data can survive pod restarts.

Configuration

Set these environment variables in your deploy context (Drone step env or secret values):

• REDIS_PERSISTENCE_ENABLED (true/false, default: true)
• REDIS_PERSISTENCE_SIZE (default: 1Gi non-prod, 10Gi prod)
• REDIS_PERSISTENCE_ACCESS_MODES (default: ReadWriteOnce)
• REDIS_PERSISTENCE_STORAGE_CLASS (default: empty, uses cluster default StorageClass)
• REDIS_PERSISTENCE_EXISTING_CLAIM (optional, default: empty)
• REDIS_PERSISTENCE_ANNOTATIONS_FILE (optional path to YAML key/value annotations)

When enabled, kube/redis/redis-persistent-volume-claim.yml is rendered and kube/redis/redis-deployment.yml mounts that claim into /var/lib/redis. When disabled, Redis falls back to emptyDir and deployment behaviour remains unchanged.

Cluster prerequisites

• A default StorageClass in the target cluster, or set REDIS_PERSISTENCE_STORAGE_CLASS explicitly.
• Sufficient capacity in the selected storage class for the requested PVC size.

How to test persistence

1. Deploy with REDIS_PERSISTENCE_ENABLED=true.
2. Confirm PVC is bound: kubectl get pvc -n <namespace>.
3. Write test data in Redis: kubectl exec -n <namespace> deploy/redis -- redis-cli SET persistence-check ok.
4. Restart Redis pod: kubectl rollout restart deploy/redis -n <namespace> (branch deploys use suffixed names).
5. Verify data survives restart: kubectl exec -n <namespace> deploy/redis -- redis-cli GET persistence-check.

Upgrade and migration notes

• PVC fields are mostly immutable after creation (for example, storage class and some access mode changes).
• If you need to change immutable PVC settings, create a new claim and set REDIS_PERSISTENCE_EXISTING_CLAIM.
• Helm-style upgrade behaviour still applies conceptually to immutable PVC constraints even though this repo deploys via kd and raw manifests.