From 67d689ff3abeb03f188a649417096c85d0f54393 Mon Sep 17 00:00:00 2001 From: initstring <26131150+initstring@users.noreply.github.com> Date: Sat, 17 Jan 2026 17:07:44 +1100 Subject: [PATCH 1/2] Simplify docker installation auth guidance --- deploy/docker/.env.example | 28 ++++++------- deploy/docker/docker-compose.yml | 24 +++++------ docs/development.md | 10 ++++- docs/installation.md | 69 +++++++++++++++----------------- 4 files changed, 65 insertions(+), 66 deletions(-) diff --git a/deploy/docker/.env.example b/deploy/docker/.env.example index 56546c1..108a48b 100644 --- a/deploy/docker/.env.example +++ b/deploy/docker/.env.example @@ -1,29 +1,27 @@ # 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. -RTAP_AUTH_URL=http://localhost:3000 +AUTH_URL=http://localhost:3000 # Secure values: generate with `openssl rand -base64 32` -RTAP_AUTH_SECRET=REPLACE_WITH_A_SECURE_RANDOM_VALUE -RTAP_INITIAL_ADMIN_EMAIL=admin@example.com +AUTH_SECRET=REPLACE_WITH_A_SECURE_RANDOM_VALUE +INITIAL_ADMIN_EMAIL=admin@example.com # Optional SSO # Demo mode (default disabled): expose a demo admin login button -RTAP_ENABLE_DEMO_MODE=false +ENABLE_DEMO_MODE=false # Register Google provider when present (optional) -#RTAP_GOOGLE_CLIENT_ID= -#RTAP_GOOGLE_CLIENT_SECRET= +#GOOGLE_CLIENT_ID= +#GOOGLE_CLIENT_SECRET= # Optional: logging level (default: debug in dev, info in prod) -#RTAP_LOG_LEVEL=info +#LOG_LEVEL=info -# Postgres -RTAP_POSTGRES_HOST=rtap-postgres -RTAP_POSTGRES_PORT="5432" -RTAP_POSTGRES_USER=postgres -RTAP_POSTGRES_PASSWORD=CHANGE_ME -RTAP_POSTGRES_DB=rtap +# Postgres (container configuration) +POSTGRES_USER=postgres +POSTGRES_PASSWORD=CHANGE_ME +POSTGRES_DB=rtap # Web app -RTAP_PORT=3000 -RTAP_DATABASE_URL=postgresql://${RTAP_POSTGRES_USER}:${RTAP_POSTGRES_PASSWORD}@${RTAP_POSTGRES_HOST}:${RTAP_POSTGRES_PORT}/${RTAP_POSTGRES_DB} +PORT=3000 +DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@rtap-postgres:5432/${POSTGRES_DB} diff --git a/deploy/docker/docker-compose.yml b/deploy/docker/docker-compose.yml index 56171f0..81ff356 100644 --- a/deploy/docker/docker-compose.yml +++ b/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) diff --git a/docs/development.md b/docs/development.md index c97a84a..fb89e75 100644 --- a/docs/development.md +++ b/docs/development.md @@ -2,10 +2,12 @@ ## 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 +# Copy the local dev env file and replace secrets cp .env.example .env # Install dependencies @@ -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. diff --git a/docs/installation.md b/docs/installation.md index d6e63c3..0619585 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,66 +1,61 @@ # Installation -Follow these instructions to set up Red Team Assessment Platform (RTAP) for production or local testing purposes. This uses pre-built Docker containers. - -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). +This guide is for running RTAP with pre-built Docker containers (production or quick local trials). +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. -```sh -cd deploy/docker +### Environment files (pick the right one) -# Copy example env file and replace secrets -cp .env.example .env +- Docker Compose: `deploy/docker/.env.example` → `deploy/docker/.env` +- Local development: `.env.example` (repo root) → `.env` -docker compose up -d +Docker Compose only reads `deploy/docker/.env`, so keep that file next to `deploy/docker/docker-compose.yml`. -# Optionally - seed demo taxonomy/operation data (FOR DEMO PURPOSES ONLY) -docker exec rtap-web npm run seed:demo +### Configure the Docker `.env` file -# Optional: enable demo admin login for trials (see Authentication below) -``` +From the repository root: -## Authentication +```sh +cd deploy/docker +cp .env.example .env +``` -### 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` (public URL users will visit) -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. +`DATABASE_URL` is already pre-wired to the postgres container (`rtap-postgres`). Keep it unless you are pointing to an external database. -**Admin bootstrap:** +### Choose authentication mode -- 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`). +RTAP supports Google SSO or a demo login button. -**Ongoing user management:** +- **Google SSO (recommended):** set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. +- **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 demos. -- Once logged in as admin, you can create additional users. -- SSO users: log in with the matching email. +For Google, configure the following in the Google Cloud console: -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. From 6da2979e35829f9515fbe4f818b678f152b83679 Mon Sep 17 00:00:00 2001 From: initstring <26131150+initstring@users.noreply.github.com> Date: Sat, 3 Jan 2026 01:00:56 +1100 Subject: [PATCH 2/2] Clarify docs --- .env.example => .env.example-dev | 3 +++ .../{.env.example => .env.example-prod} | 8 ++++--- docs/development.md | 2 +- docs/installation.md | 24 +++++++------------ 4 files changed, 17 insertions(+), 20 deletions(-) rename .env.example => .env.example-dev (82%) rename deploy/docker/{.env.example => .env.example-prod} (77%) diff --git a/.env.example b/.env.example-dev similarity index 82% rename from .env.example rename to .env.example-dev index e708a3b..f155419 100644 --- a/.env.example +++ b/.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) diff --git a/deploy/docker/.env.example b/deploy/docker/.env.example-prod similarity index 77% rename from deploy/docker/.env.example rename to deploy/docker/.env.example-prod index 108a48b..95a6e70 100644 --- a/deploy/docker/.env.example +++ b/deploy/docker/.env.example-prod @@ -7,10 +7,12 @@ AUTH_URL=http://localhost:3000 AUTH_SECRET=REPLACE_WITH_A_SECURE_RANDOM_VALUE INITIAL_ADMIN_EMAIL=admin@example.com -# Optional SSO -# Demo mode (default disabled): expose a demo admin login button +# 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 -# Register Google provider when present (optional) + +# SSO Configuration #GOOGLE_CLIENT_ID= #GOOGLE_CLIENT_SECRET= diff --git a/docs/development.md b/docs/development.md index fb89e75..7e67a29 100644 --- a/docs/development.md +++ b/docs/development.md @@ -8,7 +8,7 @@ From the repository root: ```sh # Copy the local dev env file and replace secrets -cp .env.example .env +cp .env.example-dev .env # Install dependencies npm install diff --git a/docs/installation.md b/docs/installation.md index 0619585..68525b9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,18 +1,12 @@ # Installation This guide is for running RTAP with pre-built Docker containers (production or quick local trials). + 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. - -### Environment files (pick the right one) - -- Docker Compose: `deploy/docker/.env.example` → `deploy/docker/.env` -- Local development: `.env.example` (repo root) → `.env` - -Docker Compose only reads `deploy/docker/.env`, so keep that file next to `deploy/docker/docker-compose.yml`. +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. ### Configure the Docker `.env` file @@ -20,7 +14,7 @@ From the repository root: ```sh cd deploy/docker -cp .env.example .env +cp .env.example-prod .env ``` Minimum values to edit: @@ -28,18 +22,16 @@ Minimum values to edit: - `AUTH_SECRET` (required, at least 32 characters) - `INITIAL_ADMIN_EMAIL` (your admin account) - `POSTGRES_PASSWORD` (database password) -- `AUTH_URL` (public URL users will visit) - -`DATABASE_URL` is already pre-wired to the postgres container (`rtap-postgres`). Keep it unless you are pointing to an external database. +- `AUTH_URL` (URL the app will be accessed on) ### Choose authentication mode -RTAP supports Google SSO or a demo login button. +RTAP supports SSO or a demo login button. -- **Google SSO (recommended):** set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. -- **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 demos. +- **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. -For Google, configure the following in the Google Cloud console: +For Google SSO, 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`.