fws-app

This is the FWIS management tool

Environment variables

name	description	required	default	valid	notes
FWS_ENV_NAME	Environment name	no	dev	dev,tst,pre,prd
PORT	Port number	no	3000
FWS_API_URL	API url	yes
FWS_API_KEY	API key	yes
FWS_APP_PROXY	Proxy	no
AD_CLIENT_ID	AD Client Id	yes
AD_CLIENT_SECRET	AD Client Secret	yes
AD_TENANT	AD Tenant	yes
AD_COOKIE_PASSWORD	Cookie password	yes
IS_SECURE	Secure cookie	no	false
FORCE_HTTPS	Force https	no	false
HOME_PAGE	Home page	no	http://localhost:3000
LOCAL_CACHE	Force local cache	no	true
REDIS_HOST		no
REDIS_PORT		no
REDIS_TLS		no	false
FWS_APP_GA_ID	Google analytics Id	no

Prerequisites

Node v22+

Running the application

First build the application using:

$ npm run build

This will build the css based on the govuk-frontend scss/styles.

Now the application is ready to run:

$ node index.js

Docker Setup

Prerequisites

• Docker and Docker Compose installed
• Python virtual environment (required for fws-api setup)
• fws-api cloned as a sibling directory to fws-app

Quick Start

NOTE: The fws-api localstack debugging must be disabled by ensuring that LAMBDA_DOCKER_FLAGS is not defined in https://github.com/DEFRA/fws-api/blob/development/docker/.env

The easiest way to run fws-app with Docker is using the automated startup script:

One-time setup (first time only)

example uses ~/environments/my_env but you can substitute for your own custom path for your local setup

# 1. Create a Python virtual environment
mkdir -p ~/environments
python3 -m venv ~/environments/my_env

# 2. Activate your Python virtual environment
source ~/environments/my_env/bin/activate

# 3. Install required Python packages
pip install awscli-local

# 4. Configure environment variables
# Copy docker/.env.example to docker/.env and populate the required secrets:
# - AD_CLIENT_ID
# - AD_CLIENT_SECRET
# - AD_TENANT
# - AD_COOKIE_PASSWORD

Start local environment (after one-time setup)

# 1. Activate your Python virtual environment
source ~/environments/my_env/bin/activate

# 2. Run the startup script
./docker/scripts/start-local.sh

The start-local.sh script will:

1. Validate all required environment variables are set
2. Bootstrap the fws-api in LocalStack (npm run bootstrap-debug)
3. Auto-populate the FWS_API_URL from LocalStack
4. Build and start all Docker services
5. Display the application URL: http://localhost:3000

To stop and teardown the local environment:

./docker/scripts/stop-local.sh

The stop-local.sh script will:

1. Stop and remove all Docker containers
2. Teardown the fws-api in LocalStack (npm run teardown)
3. Display completion message

Debugging

// The development base of the webapp exposes debug port 9229 so add this to your .vscode/launch.json file for debugging:
{
  "type": "node",
  "request": "attach",
  "name": "Attach to Docker",
  "address": "localhost",
  "port": 9229,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app"
}

Manual Docker Commands

Build the fws-app image only

docker build -f docker/Dockerfile -t fws-app:latest --target development .

Run with Docker Compose

# Start all services (Redis + fws-app)
docker compose -f docker/infrastructure.yml -f docker/app.yml up -d

# Start with rebuild
docker compose -f docker/infrastructure.yml -f docker/app.yml up -d --build

# Stop all services
docker compose -f docker/infrastructure.yml -f docker/app.yml down

Start individual services

# Start only Redis
docker compose -f docker/infrastructure.yml up -d fws-app-redis

# Start only fws-app
docker compose -f docker/app.yml up -d fws-app

Run unit tests in the running container

If you prefer running tests inside the app container:

# 1. Start the local environment
./docker/scripts/start-local.sh

# 2. Open new Terminal and list running containers and identify the app container name
docker ps -a

# 3. Open a shell in the app container
docker exec -it fws-app /bin/sh

# 4. (Optional) confirm the current user
whoami

# 5. Run unit tests
npm run test

You can also run tests in one command without opening an interactive shell:

docker exec -it fws-app sh -lc "npm run etest"

Troubleshooting: reset local Docker volumes

If the app starts but shows errors in the browser (for example HTTP 500/502 after switching branches), your local fws-api database volumes may be out of sync with the current schema.

Common symptoms include errors mentioning missing columns/relations (for example latest, target_area) or pg_tblspc file path issues.

Run the following to reset local development volumes and rebuild cleanly:

# 1) Stop fws-app services
cd ~/Projects/fws-app
docker compose -f docker/infrastructure.yml -f docker/app.yml down --remove-orphans || true

# 2) Stop fws-api services
cd ~/Projects/fws-api
docker compose -f docker/infrastructure.yml -f docker/networks.yml -f docker/dev-tools.yml down --remove-orphans || true

# 3) Remove local development volumes used by fws-api
docker volume rm -f fwspgdata fwspgbootstrap fwsliquibase fwspgadmin fwstables fwsindexes

# 4) Start again from fws-app
cd ~/Projects/fws-app
source ~/environments/my_env/bin/activate
./docker/scripts/start-local.sh

Note: this removes local development data only; it does not affect deployed environments.

Configuration

Environment variables are managed in docker/.env. See the Environment Variables section above for required values.

Note: Never commit secrets to docker/.env. A pre-commit hook is available to prevent this:

./install-hooks.sh

Helper Scripts

• docker/scripts/start-local.sh - Full automated setup and startup
• docker/scripts/stop-local.sh - Full automated teardown and cleanup
• docker/scripts/update-localstack-url.sh - Update FWS_API_URL from LocalStack

Network Configuration

The fws-app container connects to:

• default network - For communication with fws-app-redis
• docker_ls (LocalStack network) - For communication with the fws-api in LocalStack

Ensure LocalStack is running before starting fws-app if you need API connectivity.