Deployment Guide
This guide covers different deployment scenarios for the Homer Console.
Table of Contents
- Local Development
- Docker Standalone
- Docker Compose
- Production Deployment
- Environment Configuration
- Dependency Security
Local Development
Prerequisites
- Node.js 24 (the version the Dockerfile builds with)
- npm
- Running Homer backend
Steps
- Clone the repository and navigate to the console directory:
cd console- Install dependencies:
npm install- Create your environment file:
cp .env.example .env.local- Edit
.env.localwith your settings:
CONSOLE_HOMER_API_URL=http://localhost:8080
CONSOLE_AUTH_ENABLED=false- Start the development server:
npm run dev- Open http://localhost:3000 in your browser
Docker Standalone
Build and run only the frontend in a Docker container.
Build the Image
docker build -t homer-console:latest .Run the Container
Without Authentication
docker run -d \
--name homer-console \
-p 3000:3000 \
-e CONSOLE_HOMER_API_URL=http://your-homer-backend:8080 \
-e CONSOLE_AUTH_ENABLED=false \
homer-console:latestWith Authentication
docker run -d \
--name homer-console \
-p 3000:3000 \
-e CONSOLE_HOMER_API_URL=http://your-homer-backend:8080 \
-e CONSOLE_AUTH_ENABLED=true \
homer-console:latestCustom Port
docker run -d \
--name homer-console \
-p 8080:4000 \
-e PORT=4000 \
-e CONSOLE_HOMER_API_URL=http://your-homer-backend:8080 \
homer-console:latestDocker Compose
Run both frontend and Homer backend together using the root-level docker-compose.yml.
Setup
From the project root:
cp .env.example .env
# Required — the backend refuses to start without it
echo "HOMER_ADMIN_TOKEN=$(openssl rand -hex 24)" >> .envThe default backend config uses bearer auth, so .env.example turns on console sign-in with the token option (AUTH_ENABLED=true, CONSOLE_ALLOW_BEARER=true): sign in at /login?mode=bearer on the Token tab with the HOMER_ADMIN_TOKEN value. The token is then kept in localStorage, acceptable for this loopback-only stack. To use the console without logging in, instead set CONFIG_PATH=config/config-local.json and AUTH_ENABLED=false in .env (an unsecured backend, bound to loopback); for real logins, configure a password scheme and leave CONSOLE_ALLOW_BEARER off — see app/SERVER.md § Password Authentication.
Run
docker compose up -d
docker compose logs -f frontend # console logs
docker compose logs -f backend # backend logs (also in example/workspace/app.log)
docker compose downFor detailed Docker documentation and deployment options, see ../DOCKER.md.
Customization
Edit docker-compose.yml in the project root to customize:
- Volume mounts
- Network configuration
- The backend image
- Environment variables
The base file has no build: sections — it pulls the published release images, with the tag selected by HOMER_VERSION. Override image: to run your own:
services:
backend:
image: my-registry/homer-backend:v1.0.0Building from source is the docker-compose.build.yml overlay, which adds the build: sections back (and tags what it builds locally); see ../DOCKER.md § Quick Start.
Production Deployment
Build Optimization
The application uses Next.js standalone output for minimal image size:
// next.config.js
const nextConfig = {
output: 'standalone',
// ...
}Multi-stage Build
The Dockerfile uses multi-stage builds to minimize the final image size:
- Deps stage: Installs dependencies
- Builder stage: Builds the application
- Runner stage: Copies only the standalone build output,
.next/staticandpublic/
Health Checks
Add health checks to your deployment:
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40sReverse Proxy
When deploying behind a reverse proxy (nginx, traefik, etc.), configure accordingly:
Nginx Example
Terminate TLS at the proxy. Cookie auth sets Secure cookies by default, so a plain-HTTP deployment silently fails to authenticate — the browser will not send the session cookie back.
# Redirect plain HTTP to HTTPS.
server {
listen 80;
server_name homer-console.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name homer-console.example.com;
ssl_certificate /etc/ssl/certs/homer-console.pem;
ssl_certificate_key /etc/ssl/private/homer-console.key;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
# SSE endpoints stream for the life of a run; don't buffer or time them out.
proxy_buffering off;
proxy_read_timeout 3600s;
}
}Rate limiting behind a proxy: Homer keys its login limiter on the direct TCP peer, deliberately not
X-Forwarded-For(which a client can spoof). Behind a proxy that peer is the proxy, so all clients share one bucket. Raiseserver.loginRateLimitandserver.perCallerRateLimitaccordingly, or apply per-IP limiting at the proxy where the real client address is known.
Traefik Example
labels:
- "traefik.enable=true"
- "traefik.http.routers.homer-console.rule=Host(`homer-console.example.com`)"
- "traefik.http.services.homer-console.loadbalancer.server.port=3000"Environment Configuration
Optional Variables
| Variable | Description | Default |
|---|---|---|
CONSOLE_HOMER_API_URL | Homer backend API URL | api.baseUrl from config/default.json (http://localhost:8080) |
CONSOLE_AUTH_ENABLED | Enable authentication | false |
CONSOLE_ALLOW_BEARER | Offer bearer (token) login. Off = cookie-only (recommended; bearer tokens live in localStorage and are XSS-exfiltratable). Set true only for a bearer-only backend; it also makes Token the mode the login form opens in, since such a backend cannot accept a password. | false |
CONSOLE_ALLOWED_API_ORIGINS | Comma-separated backend origins the console may connect to. When set, the CSP connect-src is pinned to 'self' + these (a genuinely strict CSP), and the login endpoint field is restricted to them. When unset, connect-src stays open so any backend can be entered at login. | (unset) |
CONSOLE_PLUGINS | Comma-separated plugin entries: a same-origin module path under public/, optionally @<requirement> (/plugins/costs.js@admin, where the requirement is admin or a Homer Action). Remote URLs are rejected; a requirement is enforced before the module is fetched. Each entry runs with the operator's privileges in the console's origin — treat it like source you merged, and keep public/plugins/ writable only by the operator. See the console README's Plugins section and ADR-0059. | (unset) |
CONSOLE_THEMES | Comma-separated theme entries as name:path (brand-dark:/themes/brand-dark.css). The name appears in the theme dropdown; the path must be a root-relative .css file under public/, served same-origin. Remote URLs, protocol-relative paths, data:/blob: URLs, .., non-.css paths, names outside [a-z0-9-]+ and names colliding with a built-in are rejected and logged; the rest still load, and a missing file applies no tokens, so every token falls back to the :root (light) values. A theme restyles the console for every user of it — treat it like a stylesheet you approved, and keep public/themes/ writable only by the operator. See the console README's Custom themes section and ADR-0069. | (unset) |
CONSOLE_THEME_MODES | Names one CONSOLE_THEMES entry as the light theme and one as the dark theme, as light:<name>,dark:<name> (light:corp-light,dark:corp-dark). When set and valid, the theme dropdown and next-themes offer only the configured entries plus System — the built-ins light/dark/terminal/win95 are hidden, System is the default and follows the OS colour scheme onto the named pair, and a stored built-in falls back to System. Both names must be CONSOLE_THEMES entries; a missing or unknown name, a built-in name, a duplicate or an extra segment discards the setting as a whole (built-ins stay) and logs the reason once. See the console README's Custom themes section and ADR-0069. | (unset) |
PORT | Frontend server port | 3000 |
HOSTNAME | Server hostname | 0.0.0.0 |
NODE_ENV | Node environment | production |
Configuration Precedence
- Environment variables (highest priority)
.env.localfileconfig/default.json(lowest priority)
Security Considerations
Authentication
- Always use HTTPS in production when authentication is enabled
- Store tokens securely (use environment variables, not hardcoded)
- Rotate tokens regularly
- Consider using a secrets management system (Vault, AWS Secrets Manager, etc.)
CORS
If the Homer backend and console are on different origins, pin the origin on the backend (Kotlin/Ktor — server.corsAllowedOrigins in the Homer config, not an Express middleware):
server:
# Origin pin lives on the server block.
corsAllowedOrigins:
- "https://homer-console.example.com"
# Cookie settings live on the password auth scheme, not on `server` directly.
apiAuth: !<password>
users:
admin:
passwordHash: "@SYSENV:ADMIN_PASSWORD_HASH"
role: admin
sessionSecret: "@SYSENV:HOMER_SESSION_SECRET"
cookieSameSite: "none" # required for cross-origin cookie auth
cookieSecure: true # enforced when cookieSameSite is "none"An empty corsAllowedOrigins allows any origin without credential reflection, and is a startup error under password auth. Under cookieSameSite: none the origin pin becomes the primary cross-origin control rather than defence-in-depth, so pin it exactly. See app/SERVER.md § Password Authentication and README.md § Multiple instances.
CSP Headers
Do not add a CSP header at the proxy. The console already emits a per-request nonce-based policy with 'strict-dynamic' from middleware.ts, and deliberately relaxes it to 'unsafe-eval'/'unsafe-inline' on exactly one route (/agents/<name>/edit, which hosts the Monaco editor). A blanket proxy header would apply that relaxation site-wide and override the stricter policy everywhere else — strictly worse than the built-in behaviour.
Note the built-in CSP is only emitted in production builds. If you need additional headers at the proxy, add ones the app does not set (for example Strict-Transport-Security once you are HTTPS-only) rather than Content-Security-Policy.
Monitoring
Logging
The application logs to stdout/stderr. Collect logs using:
# Docker logs
docker logs -f homer-console
# Docker Compose logs
docker compose logs -f frontendMetrics
Monitor key metrics:
- Response times
- Error rates
- Memory usage
- CPU usage
Use tools like:
- Prometheus + Grafana
- DataDog
- New Relic
Troubleshooting
Cannot connect to Homer backend
Problem: Frontend shows "Failed to load processes"
Solutions:
- Verify
CONSOLE_HOMER_API_URLis correct and accessible - Check network connectivity between containers
- Ensure Homer backend is running and healthy
- Check CORS configuration on backend
- Review browser console and network tab for errors
Authentication failures
Problem: Login fails or the console keeps returning to the login page
Solutions:
- Ensure
CONSOLE_AUTH_ENABLED=trueand that the backend has a password scheme (apiAuth: !<password>or!<combined>) listing the user - Serve the console over HTTPS — cookies are
Secureby default, so a plain-HTTP deployment never sends the session back - Check that
server.corsAllowedOriginslists the console origin - Bearer login (
CONSOLE_ALLOW_BEARER=trueonly): test the token against/api/v1/heartbeat, then clear browser localStorage and try again
Port conflicts
Problem: "Port 3000 is already in use"
Solutions:
- Change the
PORTenvironment variable - Update port mappings in Docker run command
- Stop other services using the port
Build failures
Problem: Docker build fails
Solutions:
- Ensure you have enough disk space
- Clear Docker cache:
docker system prune -a - Check Dockerfile for syntax errors
- Verify all dependencies are available
Memory issues
Problem: Container runs out of memory
Solutions:
- Increase container memory limit
- Reduce
pagination.defaultLimitinconfig/default.json(compiled in; rebuild the image)
Scaling
Horizontal Scaling
The frontend is stateless and can be scaled horizontally. Remove the root compose file's container_name: homer-console first — a fixed container name allows only one replica:
services:
frontend:
# ...
deploy:
replicas: 3Use a load balancer (nginx, HAProxy, etc.) to distribute traffic.
Vertical Scaling
Adjust resource limits:
services:
frontend:
# ...
deploy:
resources:
limits:
cpus: '1'
memory: 1G
reservations:
cpus: '0.5'
memory: 512MUpdates
Rolling Updates
Rebuild and recreate the console container:
docker compose up -d --build frontendCompose stops the old container before starting the new one, so expect a short outage; for zero downtime, see below.
Zero-Downtime Deployments
Use multiple replicas and a load balancer:
- Deploy new version to a subset of replicas
- Verify health
- Gradually shift traffic
- Complete rollout
Backup and Recovery
Configuration Backup
Backup important files:
.envor.env.local- Custom configurations (
config/default.jsonis compiled into the image)
Disaster Recovery
- Keep Docker images in a registry
- Version control all configuration files
- Document custom modifications
- Test restore procedures regularly
Dependency Security
Two overrides entries pin patched copies of transitive dependencies:
dompurify(viamonaco-editor) —overrides.dompurifypins the transitive copy Monaco bundles to^3.4.16(fixing the XSS / mXSS / prototype-pollution advisories affecting<= 3.4.10and the DOM XSS affecting3.4.13–3.4.15). This avoids the npm-suggested "fix", which downgradesmonaco-editorto0.53.0. Drop the override oncemonaco-editorships a release depending on a patcheddompurify.postcss—overrides.postcsspins the transitive copy bundled by Next.js to the patched8.5.x, since the audit's automatic fix would otherwise downgrade Next.js itself.
Licensing note: lightningcss (MPL-2.0)
lightningcss is the one non-permissively-licensed package in the tree (MPL-2.0 — a weak, file-level copyleft; not proprietary). It is not a direct dependency: Tailwind CSS v4 uses it as its CSS engine (@tailwindcss/postcss → @tailwindcss/node), and Vite declares it for an optional CSS transformer the console never enables. Both paths are devDependencies, so it runs only at build/test time and is never distributed: the deployed image ships Next's output: 'standalone' trace, which does not contain it. MPL-2.0 obligations attach to distributing modified MPL-covered source files; an unmodified build-time tool imposes none on the console's Apache-2.0 code or on the CSS it emits. Kept deliberately (2026-08-18) — the only way to remove it would be downgrading to Tailwind v3, which is not worth it for a build-only dependency. License scanners flagging it should allowlist it as build-time tooling.
Support
For issues and questions:
- Check the README.md for general usage
- Review logs for error messages
- Open an issue in the Homer repository