fix: supservisord environment vars + OSS documentation (#5361)

Evgastap · EC2 Default User · web-flow · commit bcabf39c033a · 2026-01-21T13:14:32.000-08:00
* fix: add supervisord env variables &amp; update oss documentation

* fix: create all required MinIO buckets in minio-setup

---------

Co-authored-by: EC2 Default User &lt;ec2-user@ip-172-31-46-114.ec2.internal&gt;
diff --git a/Dockerfile b/Dockerfile
@@ -151,8 +151,16 @@ ENV CLICKHOUSE_HOST=http://localhost:8123
 ENV MINIO_ROOT_USER=minioadmin
 ENV MINIO_ROOT_PASSWORD=minioadmin
 
+# Default environment variables for supervisord (can be overridden at runtime with -e)
+# These are read by supervisord.conf using %(ENV_VAR)s syntax
+ENV NEXT_PUBLIC_HELICONE_JAWN_SERVICE=http://localhost:8585
+ENV S3_ENDPOINT=http://localhost:9080
+ENV S3_ACCESS_KEY=minioadmin
+ENV S3_SECRET_KEY=minioadmin
+ENV S3_BUCKET_NAME=request-response-storage
+ENV S3_PROMPT_BUCKET_NAME=prompt-body-storage
+ENV BETTER_AUTH_SECRET=change-me-in-production
 
-# Use supervisord as entrypoint
 CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
 
 # --------------------------------------------------------------------------------------------------------------------
diff --git a/docker/README.md b/docker/README.md
@@ -1,4 +1,26 @@
-# Running locally
+# Docker Setup
+
+## Quick Start: All-in-One Container
+
+For the simplest self-hosted setup, use the all-in-one Docker image:
+
+```bash
+docker pull helicone/helicone-all-in-one:latest
+docker run -d --name helicone -p 3000:3000 -p 8585:8585 -p 9080:9080 helicone/helicone-all-in-one:latest
+```
+
+**Ports:**
+- `3000` - Web dashboard
+- `8585` - Jawn API + LLM proxy
+- `9080` - MinIO S3 storage (for request/response bodies)
+
+For production deployments with custom domains, see the [official self-hosting docs](https://docs.helicone.ai/getting-started/self-host/docker).
+
+---
+
+# Local Development
+
+## Running with Docker Compose
 
 ```
 cp .env.example .env
@@ -8,12 +30,12 @@ docker compose up
 NOTE: To create a user go to http://localhost:54323/project/default/auth/users and add your account.
 You can use this account to sign into Helicone at localhost:3000 via your browser.
 
-Default URLs:
+**Default URLs (Development):**
 
 - Helicone Webpage: localhost:3000
-- Helicone OpenAI Proxy: localhost:8787
-- Helicone API: localhost:8788
-- Helicone GATEWAY: localhost:8790
+- Helicone Jawn API/Proxy: localhost:8585
+- OpenAI Proxy Worker: localhost:8787 (when running workers separately)
+- Helicone API Worker: localhost:8788 (when running workers separately)
 
 # Maintenance
 
diff --git a/docs/getting-started/self-host/cloud.mdx b/docs/getting-started/self-host/cloud.mdx
@@ -9,13 +9,99 @@ description: "Set up Helicone on cloud infrastructure. Step-by-step instructions
 
 Create your node on the cloud. For example, on AWS, you can create an EC2 instance.
 Make sure that the instance has enough memory and disk space to run Helicone.
-For example, you can use the `m5.2xlarge` instance type on AWS.
+For example, you can use the `m5.xlarge` instance type on AWS.
 
-Recommend Requirements
+Recommended Requirements
 
-- 8 vCPUs
-- 32 GB RAM
-- 250 GB disk space
+- 4 vCPUs
+- 16 GB RAM
+- 100 GB disk space
+
+## Option 1: All-in-One Image (Recommended)
+
+The simplest approach uses the pre-built `helicone-all-in-one` Docker image.
+
+### Within your remote machine
+
+[Install Docker](https://docs.docker.com/engine/install/)
+
+Run the container with your server's public IP:
+
+```bash
+export PUBLIC_URL="http://YOUR_IP:3000"
+export JAWN_URL="http://YOUR_IP:8585"
+export S3_URL="http://YOUR_IP:9080"
+
+docker run -d \
+  --name helicone \
+  -p 3000:3000 \
+  -p 8585:8585 \
+  -p 9080:9080 \
+  -e SITE_URL="$PUBLIC_URL" \
+  -e BETTER_AUTH_URL="$PUBLIC_URL" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
+  -e NEXT_PUBLIC_APP_URL="$PUBLIC_URL" \
+  -e NEXT_PUBLIC_HELICONE_JAWN_SERVICE="$JAWN_URL" \
+  -e NEXT_PUBLIC_IS_ON_PREM=true \
+  -e S3_ENDPOINT="$S3_URL" \
+  helicone/helicone-all-in-one:latest
+```
+
+See the [Docker guide](/getting-started/self-host/docker) for environment variables, user setup, and troubleshooting.
+
+### Adding HTTPS through a reverse proxy (optional)
+
+If you want to serve Helicone through a custom domain with HTTPS, you'll need a reverse proxy. Caddy is one option that provides automatic HTTPS with Let's Encrypt certificates. You can also use nginx, Traefik, or any other reverse proxy.
+
+1. Point a domain to your server's IP (A record), e.g., `helicone-api.yourdomain.com`
+
+2. Install Caddy:
+```bash
+curl -L "https://github.com/caddyserver/caddy/releases/latest/download/caddy_linux_amd64.tar.gz" -o caddy.tar.gz
+tar -xzf caddy.tar.gz caddy
+sudo mv caddy /usr/local/bin/
+sudo chmod +x /usr/local/bin/caddy
+```
+
+3. Create `/etc/caddy/Caddyfile`:
+```caddyfile
+helicone-api.yourdomain.com {
+    reverse_proxy localhost:8585
+}
+```
+
+4. Run Caddy:
+```bash
+sudo mkdir -p /var/log/caddy /etc/caddy
+
+sudo tee /etc/systemd/system/caddy.service > /dev/null <<'EOF'
+[Unit]
+Description=Caddy web server
+After=network.target
+
+[Service]
+Type=notify
+User=root
+ExecStart=/usr/local/bin/caddy run --config /etc/caddy/Caddyfile
+ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl enable caddy
+sudo systemctl start caddy
+```
+
+Now you can access the API via `https://helicone-api.yourdomain.com`.
+
+---
+
+## Option 2: Build from Source
+
+For more control, you can build and run Helicone from source using Docker Compose.
 
 ### Within your remote machine
 
@@ -35,7 +121,9 @@ cp .env.example .env
 ./helicone-compose.sh helicone up
 ```
 
-### Assuming you have your ssh config setup like this...
+### Accessing via SSH tunnel
+
+Assuming you have your ssh config setup like this:
 
 ```
 Host helicone
@@ -44,7 +132,7 @@ Host helicone
     IdentityFile ~/Desktop/secret.pem
 ```
 
-Let's test it by running this command on your localhost
+Test it by running this command on your localhost:
 
 ```bash
 ssh -N \
@@ -65,7 +153,7 @@ After you add a user, you can connect to the dashboard at http://localhost:3000/
 
 The proxy is setup at localhost:8787 for OpenAI.
 
-You can test it works by adding a new key on the http://localhost:3000 and then running this command on your localhost
+You can test it works by adding a new key on the http://localhost:3000 and then running this command on your localhost:
 
 ```bash
 # Test command
@@ -92,6 +180,10 @@ curl --request POST \
 
 You should see all the data show up on Helicone.
 
+---
+
+## Production Checklist
+
 The next steps before becoming production ready are:
 
 1. Follow the instructions [here](https://supabase.com/docs/guides/self-hosting/docker#securing-the-dashboard) like
diff --git a/docs/getting-started/self-host/docker.mdx b/docs/getting-started/self-host/docker.mdx
@@ -7,21 +7,169 @@ description: "Deploy Helicone using Docker. Quick setup guide for running a cont
 
 To run all services in a single Docker container, you can use the `helicone-all-in-one` image.
 
+## Quick Start (Local)
+
 Get [Docker](https://docs.docker.com/get-docker/) and run the container:
+
 ```bash
-docker pull helicone/helicone-all-in-one:v2025.08.08
-docker run -d --name helicone-all-in-one -p 3000:3000 -p 8585:8585 -p 5432:5432 -p 8123:8123 -p 9000:9000 helicone/helicone-all-in-one:v2025.08.08
+docker pull helicone/helicone-all-in-one:latest
+docker run -d \
+  --name helicone \
+  -p 3000:3000 \
+  -p 8585:8585 \
+  -p 9080:9080 \
+  helicone/helicone-all-in-one:latest
 ```
 
+Access the dashboard at `http://localhost:3000`.
+
 ## Example to test the Jawn service
+
 ```bash
-curl --location 'http://localhost:8585/v1/gateway/oai/v1/completions' \
+curl --location 'http://localhost:8585/v1/gateway/oai/v1/chat/completions' \
 --header "Content-Type: application/json" \
---header "Authorization: Bearer {{OPENAI_API_KEY}}" \
---header "Helicone-Auth: Bearer {{HELICONE_API_KEY}}" \
+--header "Authorization: Bearer $OPENAI_API_KEY" \
+--header "Helicone-Auth: Bearer $HELICONE_API_KEY" \
 --data '{
     "model": "gpt-4o-mini",
-    "prompt": "Count to 5",
-    "stream": false
+    "messages": [{"role": "user", "content": "Hello"}]
   }'
 ```
+
+## Production Setup (Remote Server)
+
+When deploying to a remote server (EC2, VPS, etc.), configure your server's public IP or domain:
+
+```bash
+# Replace YOUR_IP with your server's public IP or domain
+export PUBLIC_URL="http://YOUR_IP:3000"
+export JAWN_URL="http://YOUR_IP:8585"
+export S3_URL="http://YOUR_IP:9080"
+
+docker run -d \
+  --name helicone \
+  -p 3000:3000 \
+  -p 8585:8585 \
+  -p 9080:9080 \
+  -e SITE_URL="$PUBLIC_URL" \
+  -e BETTER_AUTH_URL="$PUBLIC_URL" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
+  -e NEXT_PUBLIC_APP_URL="$PUBLIC_URL" \
+  -e NEXT_PUBLIC_HELICONE_JAWN_SERVICE="$JAWN_URL" \
+  -e NEXT_PUBLIC_IS_ON_PREM=true \
+  -e S3_ENDPOINT="$S3_URL" \
+  helicone/helicone-all-in-one:latest
+```
+
+## Environment Variables
+
+The container uses these environment variables (with defaults for local development):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NEXT_PUBLIC_HELICONE_JAWN_SERVICE` | `http://localhost:8585` | URL browsers use to reach the API. **Must be public URL for remote deployments.** |
+| `S3_ENDPOINT` | `http://localhost:9080` | URL browsers use for presigned URLs. **Must be public URL for remote deployments.** |
+| `S3_ACCESS_KEY` | `minioadmin` | MinIO access key |
+| `S3_SECRET_KEY` | `minioadmin` | MinIO secret key |
+| `S3_BUCKET_NAME` | `request-response-storage` | S3 bucket for request/response bodies |
+| `BETTER_AUTH_SECRET` | `change-me-in-production` | Auth secret. **Generate a secure value for production.** |
+| `SITE_URL` | - | Public URL of the web dashboard |
+| `BETTER_AUTH_URL` | - | Same as SITE_URL |
+| `NEXT_PUBLIC_APP_URL` | - | Same as SITE_URL |
+| `NEXT_PUBLIC_IS_ON_PREM` | - | Set to `true` for non-localhost deployments |
+
+## Port Requirements
+
+| Port | Service | Required For |
+|------|---------|--------------|
+| 3000 | Web Dashboard | Browser access |
+| 8585 | Jawn API + LLM Proxy | Browser API calls, LLM proxying |
+| 9080 | MinIO S3 | Request/response body storage |
+| 5432 | PostgreSQL | Internal (can be restricted) |
+| 8123 | ClickHouse | Internal (can be restricted) |
+
+**Important:** Ports 3000, 8585, and 9080 must be accessible from browsers accessing the dashboard.
+
+## User Account Setup
+
+### Create Account
+
+Navigate to `http://YOUR_IP:3000/signup` and create your account.
+
+### Email Verification
+
+The container doesn't include email services. Manually verify users:
+
+```bash
+docker exec -u postgres helicone psql -d helicone_test -c \
+  "UPDATE \"user\" SET \"emailVerified\" = true WHERE email = 'your@email.com';"
+```
+
+### Organization Setup
+
+Users need an organization. If you see "No organization ID found" errors:
+
+```bash
+# Get your user ID
+docker exec -u postgres helicone psql -d helicone_test -c \
+  "SELECT id, email FROM \"user\" WHERE email = 'your@email.com';"
+
+# Create organization (save the returned ID)
+docker exec -u postgres helicone psql -d helicone_test -c \
+  "INSERT INTO organization (name, is_personal) VALUES ('My Org', true) RETURNING id;"
+
+# Add user to organization (replace USER_ID and ORG_ID)
+docker exec -u postgres helicone psql -d helicone_test -c \
+  "INSERT INTO organization_member (\"user\", organization, org_role) \
+   VALUES ('USER_ID', 'ORG_ID', 'admin');"
+```
+
+## Supported LLM Providers
+
+- OpenAI: `http://YOUR_IP:8585/v1/gateway/oai/v1/chat/completions`
+- Anthropic: `http://YOUR_IP:8585/v1/gateway/anthropic/v1/messages`
+
+Other providers (Vertex AI, AWS Bedrock, Azure OpenAI) are not supported in the self-hosted version.
+
+## Important Notes
+
+### Data Persistence
+
+Container restarts will wipe all data. For production, mount Docker volumes:
+
+```bash
+-v helicone-postgres:/var/lib/postgresql/data \
+-v helicone-clickhouse:/var/lib/clickhouse \
+-v helicone-minio:/data
+```
+
+### Security
+
+Port 8585 does not require authentication for proxying requests. Anyone with access can proxy LLM requests through your endpoint. Restrict access via firewall rules.
+
+### HTTPS
+
+For HTTPS support, use a reverse proxy (Caddy, nginx, Traefik) in front of the container. See the [Cloud Deployment guide](/getting-started/self-host/cloud) for a Caddy example.
+
+## Troubleshooting
+
+### API calls fail with connection refused
+
+The web app tries to connect to `localhost:8585` instead of your public IP. Verify the environment variable was set:
+
+```bash
+curl http://YOUR_IP:3000/__ENV.js | grep JAWN
+# Should show your public IP, not localhost
+```
+
+### Infinite redirect loop
+
+Missing `NEXT_PUBLIC_IS_ON_PREM=true` environment variable.
+
+### "Invalid origin" error on sign-in
+
+All URL environment variables must use the same origin (public IP or domain). Don't mix `localhost` with public IPs.
+
+### "No organization ID found" error
+
+User needs to be added to an organization. See the Organization Setup section above.
diff --git a/supervisord.conf b/supervisord.conf
