diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..b0b7c45
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,23 @@
+# copy this to .env and fill in your own values
+
+# the public address of your instance
+INSTANCE_URL=https://crosswords.example.com
+CORS_ORIGIN=https://crosswords.example.com
+
+# webauthn / passkeys
+RP_ID=crosswords.example.com
+RP_ORIGIN=https://crosswords.example.com
+
+# activitypub federation
+AP_DOMAIN=crosswords.example.com
+AP_ACTOR_NAME=cruciverb
+
+# host port for the puzzle page
+PORT=8484
+
+# set to true when nginx/caddy sits in front and sets x-forwarded-for
+TRUST_PROXY=false
+
+# at-rest encryption for user data - generate one with
+#   openssl rand -hex 32
+DATA_ENC_KEY=
\ No newline at end of file
diff --git a/README.md b/README.md
index 57c5b16..1d6f22b 100644
--- a/README.md
+++ b/README.md
@@ -148,10 +148,12 @@ The built image is published on the git server, so there's nothing to compile:
 
 ```bash
 docker login git.lashman.live
+cp docker-compose.example.yml docker-compose.yml
+cp .env.example .env
 docker compose up -d
 ```
 
-That pulls the image, mounts a ./data directory, and serves the puzzle on port 8484. Before first start, edit the compose file: set `INSTANCE_URL` and the federation names to your real domain, and add a `DATA_ENC_KEY` if you want storage encryption.
+That pulls the image, mounts a ./data directory, and serves the puzzle on port 8484. Before first start, set your real domain and federation names in .env, and add a DATA_ENC_KEY if you want storage encryption.
 
 Prefer to run from source?
 
diff --git a/docker-compose.yml b/docker-compose.example.yml
similarity index 55%
rename from docker-compose.yml
rename to docker-compose.example.yml
index 4568e57..dd48033 100644
--- a/docker-compose.yml
+++ b/docker-compose.example.yml
@@ -1,5 +1,8 @@
 name: cruciverb
 
+# copy this to docker-compose.yml (or point compose at it with -f) and
+# copy .env.example to .env before starting
+
 services:
   app:
     image: git.lashman.live/lashman/cruciverb:latest
@@ -28,24 +31,24 @@ services:
       STATIC_DIR: /app/static
       RUST_LOG: info
 
-      # where your instance lives - set this before first start
-      INSTANCE_URL: http://localhost:8484
-      CORS_ORIGIN: http://localhost:8484
+      # where your instance lives
+      INSTANCE_URL: ${INSTANCE_URL:-http://localhost:8484}
+      CORS_ORIGIN: ${CORS_ORIGIN:-http://localhost:8484}
 
       # webauthn / passkeys
-      RP_ID: localhost
-      RP_ORIGIN: http://localhost:8484
+      RP_ID: ${RP_ID:-localhost}
+      RP_ORIGIN: ${RP_ORIGIN:-http://localhost:8484}
 
       # activitypub federation
-      AP_DOMAIN: localhost
-      AP_ACTOR_NAME: cruciverb
+      AP_DOMAIN: ${AP_DOMAIN:-localhost}
+      AP_ACTOR_NAME: ${AP_ACTOR_NAME:-cruciverb}
 
       # admin - leave empty, use first-run setup via browser instead
       ADMIN_PATH: /admin
 
-      # enable if you sit behind a trusted reverse proxy that sets x-forwarded-for
-      # TRUST_PROXY: "true"
+      # set to true when nginx/caddy sits in front and sets x-forwarded-for
+      TRUST_PROXY: ${TRUST_PROXY:-false}
 
-      # set to enable at-rest encryption of user data. make one with:
+      # at-rest encryption for user data - generate yours with
       #   openssl rand -hex 32
-      # DATA_ENC_KEY: ""
\ No newline at end of file
+      DATA_ENC_KEY: ${DATA_ENC_KEY:-}
\ No newline at end of file