Simplify Docker installation flow and standardize env variables

.env.example → .env.example-dev

@@ -1,4 +1,6 @@
 # Example environment variables for local development.
+# Do NOT use this file for production deployments - instead use the
+# .env.example file included in the deploy/docker file.
 
 # Prisma (PostgreSQL by default)
 DATABASE_URL="postgresql://rtap:rtap@localhost:5432/rtap"
@@ -22,6 +24,7 @@ AUTH_TRUST_HOST=true
 
 # Optional: enable demo login (default: disabled)
 # Set to "true" to expose a demo admin login button on the sign-in screen.
+# WARNING: This will allow login with to anyone who can acccess the page.
 ENABLE_DEMO_MODE=false
 
 # Optional: logging level (default: debug in dev, info in prod)

deploy/docker/.env.example-prod

@@ -0,0 +1,29 @@
+# Full base URL where the app will be reachable (include http:// or https://).
+# Cookies are sent over HTTPS only when this starts with https://.
+# If you put a TLS-terminating proxy in front of rtap-web, use its public URL.
+AUTH_URL=http://localhost:3000
+
+# Secure values: generate with `openssl rand -base64 32`
+AUTH_SECRET=REPLACE_WITH_A_SECURE_RANDOM_VALUE
+INITIAL_ADMIN_EMAIL=admin@example.com
+
+# Optional: enable demo login (default: disabled)
+# Set to "true" to expose a demo admin login button on the sign-in screen.
+# WARNING: This will allow login with to anyone who can acccess the page.
+ENABLE_DEMO_MODE=false
+
+# SSO Configuration 
+#GOOGLE_CLIENT_ID=
+#GOOGLE_CLIENT_SECRET=
+
+# Optional: logging level (default: debug in dev, info in prod)
+#LOG_LEVEL=info
+
+# Postgres (container configuration)
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=CHANGE_ME
+POSTGRES_DB=rtap
+
+# Web app
+PORT=3000
+DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@rtap-postgres:5432/${POSTGRES_DB}

deploy/docker/docker-compose.yml

@@ -3,9 +3,9 @@ services:
     image: postgres:16-alpine
     container_name: rtap-postgres
     environment:
-      POSTGRES_USER: ${RTAP_POSTGRES_USER}
-      POSTGRES_PASSWORD: ${RTAP_POSTGRES_PASSWORD}
-      POSTGRES_DB: ${RTAP_POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
     volumes:
       - rtap-postgres-data:/var/lib/postgresql/data
     restart: unless-stopped
@@ -17,16 +17,16 @@ services:
       - rtap-postgres
     environment:
       NODE_ENV: production
-      PORT: ${RTAP_PORT}
-      DATABASE_URL: ${RTAP_DATABASE_URL}
-      AUTH_URL: ${RTAP_AUTH_URL}
-      AUTH_SECRET: ${RTAP_AUTH_SECRET}
-      INITIAL_ADMIN_EMAIL: ${RTAP_INITIAL_ADMIN_EMAIL}
-      ENABLE_DEMO_MODE: ${RTAP_ENABLE_DEMO_MODE}
-      GOOGLE_CLIENT_ID: ${RTAP_GOOGLE_CLIENT_ID}
-      GOOGLE_CLIENT_SECRET: ${RTAP_GOOGLE_CLIENT_SECRET}
+      PORT: ${PORT}
+      DATABASE_URL: ${DATABASE_URL}
+      AUTH_URL: ${AUTH_URL}
+      AUTH_SECRET: ${AUTH_SECRET}
+      INITIAL_ADMIN_EMAIL: ${INITIAL_ADMIN_EMAIL}
+      ENABLE_DEMO_MODE: ${ENABLE_DEMO_MODE}
+      GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
+      GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET}
     ports:
-      - "${RTAP_PORT}:${RTAP_PORT}"
+      - "${PORT}:${PORT}"
     restart: unless-stopped
 
 # If you need TLS, place your own reverse proxy (e.g., Traefik, Caddy, Nginx)

docs/development.md

@@ -2,11 +2,13 @@
 
 ## Setup
 
-Local development uses the Node.js dev server running directly on your machine with a container running Postgres for the DB. This allows you to easily edit source files and quickly review the changes, while also matching the production schema and migration behavior exactly.
+Local development uses the Node.js dev server running directly on your machine with a container running Postgres for the DB. This lets you edit source files and quickly review changes while matching the production schema and migration behavior.
+
+From the repository root:
 
 ```sh
-# Copy example env file and replace secrets
-cp .env.example .env
+# Copy the local dev env file and replace secrets
+cp .env.example-dev .env
 
 # Install dependencies
 npm install
@@ -32,6 +34,10 @@ docker compose -f deploy/docker/docker-compose.dev.yml down
 docker volume rm docker_dev-postgres-data
 ```
 
+### Environment variables
+
+Local development uses the same env variable names as Docker (for example, `AUTH_SECRET`, `AUTH_URL`, `DATABASE_URL`). The local `.env.example` also includes `TEST_DATABASE_URL` for the test runner.
+
 ## Testing
 
 The test suites relies on the Postgres container running. It uses a test database defined in your `.env` file - `TEST_DATABASE_URL` as it wipes, loads, and migrates as part of the testing.

docs/installation.md

@@ -1,66 +1,53 @@
 # Installation
 
-Follow these instructions to set up Red Team Assessment Platform (RTAP) for production or local testing purposes. This uses pre-built Docker containers.
+This guide is for running RTAP with pre-built Docker containers (production or quick local trials).
 
-For development environments, you'll probably instead want to run a local npm dev server - not a pre-built container. Additional information is available [here](./development.md).
+If you are developing on the codebase, use the local dev workflow instead: [Local Development](./development.md).
 
 ## Docker Installation
 
-The provided `deploy/docker/docker-compose.yml` file does not include a reverse proxy; configure your own with TLS.
+The provided `docker-compose.yml` file does not include a reverse proxy. For production usage, you'll want to add your own reverse proxy (Caddy, Traefik, nginx, etc) and configure TLS.
 
-```sh
-cd deploy/docker
-
-# Copy example env file and replace secrets
-cp .env.example .env
+### Configure the Docker `.env` file
 
-docker compose up -d
-
-# Optionally - seed demo taxonomy/operation data (FOR DEMO PURPOSES ONLY)
-docker exec rtap-web npm run seed:demo
+From the repository root:
 
-# Optional: enable demo admin login for trials (see Authentication below)
+```sh
+cd deploy/docker
+cp .env.example-prod .env
 ```
 
-## Authentication
-
-### How it Works
+Minimum values to edit:
 
-Authentication is SSO-only, with an optional demo-mode button for trials.
+- `AUTH_SECRET` (required, at least 32 characters)
+- `INITIAL_ADMIN_EMAIL` (your admin account)
+- `POSTGRES_PASSWORD` (database password)
+- `AUTH_URL` (URL the app will be accessed on)
 
-Currently, only Google SSO is enabled. However, [NextAuth supports tons of providers](https://next-auth.js.org/v3/configuration/providers#oauth-providers). Open an issue and I will add providers for you.
+### Choose authentication mode
 
-**Admin bootstrap:**
+RTAP supports SSO or a demo login button.
 
-- On first run, the application creates an admin account using `INITIAL_ADMIN_EMAIL` from your `.env`.
-- If using SSO, sign in with the matching account and it will just work.
-- If using demo mode, click "Sign in as Demo Admin" (requires `ENABLE_DEMO_MODE=true`).
+- **SSO (recommended):** configure your provider's details (like Google client ID/secret) using the variable names provided in the .env file.
+- **Demo mode:** set `ENABLE_DEMO_MODE=true`. This exposes a “Sign in as Demo Admin” button and **anyone with access to the sign-in page can log in without an account**. Use only for isolated testing or demos.
 
-**Ongoing user management:**
+For Google SSO, configure the following in the Google Cloud console:
 
-- Once logged in as admin, you can create additional users.
-- SSO users: log in with the matching email.
-
-Accounts must be created inside the platform; SSO logins for unknown emails will be rejected.
+- Authorized JavaScript origins: matches `AUTH_URL` from `.env`.
+- Authorized redirect URIs: `AUTH_URL` + `/api/auth/callback/google`.
 
-### Configuration Info
+### Start the containers
 
-Authentication options are configured in your `.env` file. The names are slightly different depending on whether you are doing local development or docker compose - the correct values are provided in the appropriate `.env-example` files.
+From the repository root:
 
-```
-# Demo mode: expose a demo admin login button on the sign-in page
-ENABLE_DEMO_MODE=false
+```sh
+cd deploy/docker
+docker compose up -d
 
-# Configuring the following values will enable Google SSO
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
+# Optional - seed demo taxonomy/operation data (FOR DEMO PURPOSES ONLY)
+docker exec rtap-web npm run seed:demo
 ```
 
-For Google, configure the following in the Google Cloud console:
-
-- Authorized JavaScript origins: matches `AUTH_URL` from `.env`.
-- Authorized redirect URIs: `AUTH_URL` + `/api/auth/callback/google`.
-
 ## Logging
 
 - Server logs emit to stdout/stderr (structured JSON in production, pretty in development). Rely on Docker and the host OS for collection and rotation.