Skip to main content

Configuration

hosting-service reads configuration from environment variables. Copy .env.example to .env for local runs. Pass the same keys to Docker, Coolify, or your orchestrator in production.

For the shared Shellui compose stack (shellui/shellui/dev), see Local dev stack for port 8003, internal identity URLs, and the HOSTING_* keys in dev/.env.local.

An empty boolean uses the default. 1, true, yes, and on are true. Any other value, including false, is false. Byte sizes accept a bare integer or a K, M, G, or T suffix. Each suffix is a multiple of 1024, so 100M is 104857600 bytes.

Generate the env​

python manage.py generate_env --host hosting.example.com prints every production setting with a fresh SECRET_KEY. It runs with no env, database or Redis. Replace each change-me value. Add --optional to also list the optional settings with their defaults. The output holds secrets, so store it in a secret manager and never commit it.

.env.example is generated from config/env_registry.py with python manage.py generate_env --example > .env.example. A test fails when the registry, the code, this page or .env.example drift apart.

Required to start​

SECRET_KEY is required in every mode. Django uses it to sign sessions and CSRF tokens. With DEBUG=false it must be at least 50 characters and not a placeholder, otherwise startup fails. The error names the variable and never prints its value.

.env.example leaves SECRET_KEY empty. manage.py check --deploy reports authapi.E005 when DEBUG=false and the key is empty, starts with django-insecure-, matches another known placeholder, or is shorter than 50 characters. The container entrypoint runs that check before it serves traffic.

Required when DEBUG is false​

The Docker image sets DEBUG=false. Startup fails until these are set:

VariablePurpose
IDENTITY_ISSUERJWT iss must match this value
IDENTITY_AUDIENCEJWT aud must match this value
IDENTITY_JWKS_FILE, IDENTITY_JWKS, IDENTITY_JWKS_URL, or IDENTITY_SERVICE_URLJWKS for JWT verification. Pin with IDENTITY_JWKS_FILE or IDENTITY_JWKS, or fetch from IDENTITY_JWKS_URL or {IDENTITY_SERVICE_URL}/.well-known/jwks.json. At least one must be set; the service does not fall back to localhost when DEBUG=false
HOSTING_APP_DOMAINApps domain, for example shellui.app, or eu.shellui.app for a region. Used in browse links, OAuth redirect sync, and ALLOWED_HOSTS

HOSTING_DEBUG_OPEN=true is also refused while DEBUG=false. JWT_HS256_FALLBACK_SECRET is refused unless you also set ALLOW_JWT_HS256_FALLBACK=true.

Runtime​

VariableDefaultPurpose
DEBUGfalseLocal mode. The image sets false. Never enable it in production
LOG_LEVELINFO, or DEBUG when DEBUG=truePython log level
SETUP_TOKENemptyOne-time token for the web form that creates the first superuser when DEBUG=false
HOSTING_SERVICE_PORT8003Host port published by Docker Compose. Gunicorn inside the image listens on 8000
ALLOWED_HOSTSlocalhost, 127.0.0.1Comma-separated hostnames, no scheme
CSRF_TRUSTED_ORIGINSlocal dev origins and https://admin.shellui.comFull origins for Django admin form posts
DJANGO_ADMIN_ENABLEDtruefalse removes /admin/ routes

When HOSTING_ALLOW_ANY_HOST is on (the default while DEBUG=true), ALLOWED_HOSTS includes *. Otherwise the service adds .{HOSTING_APP_DOMAIN} so app subdomains are allowed.

Identity and JWT​

VariableDefaultPurpose
IDENTITY_SERVICE_URLemptyidentity-service base URL for server-to-server OAuth redirect sync. In the local dev stack, set this to http://identity:8000 while IDENTITY_ISSUER stays http://localhost:8001. If it is empty and JWKS is pinned (IDENTITY_JWKS or IDENTITY_JWKS_FILE), sync uses the origin of IDENTITY_JWKS_URL when that URL ends in /.well-known/jwks.json. http://localhost:8000 and http://127.0.0.1:8000 are ignored
IDENTITY_JWKS_URL{IDENTITY_SERVICE_URL}/.well-known/jwks.json when IDENTITY_SERVICE_URL is set, else http://localhost:8000/.well-known/jwks.json in local devJWKS fetch URL when no document is pinned. Set explicitly (for example http://identity:8000/.well-known/jwks.json) when the issuer is public but JWKS must be fetched on the internal network
IDENTITY_JWKS_FILEemptyPath to a JWKS file. Relative paths are from the repository root
IDENTITY_JWKSemptyJWKS JSON in the environment, used when no file is set
IDENTITY_ISSUERemptyExpected iss. Required when DEBUG=false
IDENTITY_AUDIENCEemptyExpected aud. Required when DEBUG=false
JWKS_CACHE_TTL900Seconds to cache a fetched JWKS document
JWKS_TIMEOUT15Seconds for one JWKS HTTP call
JWKS_RETRIES2Retries when fetching JWKS
HOSTING_SERVICE_ISSUERemptyPublic origin of this service, the iss of its internal MCP assertions to Identity. Set the same HOSTING_SERVICE_ISSUER on Identity. Unset: MCP calls to Identity fail closed
HOSTING_SERVICE_SIGNING_KEYemptyRSA private key (PEM, 2048 bits or more) that signs internal MCP assertions (RS256). Public key served at /.well-known/jwks.json. Never log or commit it
HOSTING_SERVICE_SIGNING_KEY_FILEemptyPath to that PEM instead of the variable. Relative paths are from the repository root. Wins over HOSTING_SERVICE_SIGNING_KEY
JWT_ALGORITHMSRS256Comma-separated algorithms accepted for RS256 verification
JWT_HS256_FALLBACK_SECRETemptyHS256 secret for local identity debug tokens. Set it to the identity SECRET_KEY
ALLOW_JWT_HS256_FALLBACKfalseAllow the HS256 secret when DEBUG=false
IDENTITY_SYNC_TIMEOUT10Seconds for the OAuth redirect sync call
IDENTITY_DELEGATED_AGENT_AUTHORITY_PATH/api/v1/mcp/internal/mcp-agent-delegated-authorityIdentity internal route for the live delegated agent row check (POST JSON matches the token). Retire alternate spellings; canonical path is in identity-service docs

See JWT and claim trust.

Public URLs and serving​

VariableDefaultPurpose
HOSTING_APP_DOMAINshellui.local when DEBUG=true, else requiredDomain written into API browse links
HOSTING_APP_SCHEMEhttp when DEBUG=true, else httpsScheme of those links
HOSTING_ALLOW_ANY_HOSTsame as DEBUGAccept any Host header. Leave this off in production
HOSTING_PREVIEW_TTL_DAYS7Days added to expires_at when a preview finalize succeeds
HOSTING_SERVE_CACHE_TTL_SECONDS45In-process cache of slug-to-app lookups. 0 disables it. Cleared on finalize and rollback
HOSTING_REQUEST_LOG_ENABLEDtrueWhen true, records one anonymized row per HTTP response on app subdomains (method, path, status, optional request id) for operations APIs
HOSTING_REQUEST_LOG_MAX_PER_APP5000Deletes oldest rows after this many per app
HOSTING_REQUEST_LOG_PAGE_MAX200Maximum limit on GET .../logs/requests
HOSTING_RUNTIME_LOG_MAX_LINES500Upper cap on the limit query for GET .../logs/runtime (response stays empty until a runtime exists)
HOSTING_DEBUG_OPENfalseSkip the company waitlist. Refused when DEBUG=false. .env.example sets true for local clones

The public URL is {scheme}://{slug}.{HOSTING_APP_DOMAIN}/. Serving itself uses the first hostname label, not only this domain. HOSTING_APP_DOMAIN and www.{HOSTING_APP_DOMAIN} show the landing page. See Preview sites and public URLs.

Use a different registrable domain from identity-service and Django admin. shellui.app for hosted apps and shellui.com for identity and admin keeps a cookie set on an app host from reaching those services. manage.py check warns (hosting.W001) when the parent domain matches a configured service URL.

Quotas​

VariableDefaultPurpose
HOSTING_MAX_APPS_PER_COMPANY5App rows per company. Preview creates skip expired sites. POST /hosting/v1/apps counts every row
HOSTING_MAX_DEPLOYMENTS_PER_APP20Deployment rows kept per app, including superseded ones
HOSTING_MAX_UPLOAD_BYTES100MMaximum gzip archive size
HOSTING_MAX_EXTRACT_FILES5000Maximum regular files extracted from one archive
HOSTING_MAX_EXTRACT_BYTES500MMaximum total uncompressed size
HOSTING_ARTIFACT_UPLOAD_URL_EXPIRES900Lifetime in seconds for MCP artifact upload URLs (presigned S3 or direct hosting PUT)
HOSTING_MAX_EXTRACT_FILE_BYTESsame as the upload capMaximum size of one extracted file
DATA_UPLOAD_MAX_MEMORY_SIZE12MDjango in-memory limit for form and JSON bodies. Artifact uploads are streamed and only capped by HOSTING_MAX_UPLOAD_BYTES

Artifact storage​

VariableDefaultPurpose
HOSTING_BACKENDfilesystemfilesystem or s3
MEDIA_ROOTdata/media, /app/data/media in DockerFilesystem root. Artifacts live in artifacts/ under it
HOSTING_KEY_PREFIXhostingKey prefix in front of every artifact path
AWS_STORAGE_BUCKET_NAMEemptyRequired when HOSTING_BACKEND=s3
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYemptyS3 credentials
AWS_S3_REGION_NAMEus-east-1Region. Inferred from the endpoint when possible
AWS_S3_ENDPOINT_URLemptyCustom S3 endpoint. Leave empty for AWS
AWS_S3_CUSTOM_DOMAINemptyPublic host for the bucket, if it differs from the endpoint
AWS_S3_SIGNATURE_VERSIONs3v4Signature version
AWS_S3_ADDRESSING_STYLEinferredpath, virtual, or auto

Objects are stored at {HOSTING_KEY_PREFIX}/{app_id}/deployments/{deployment_id}/artifact.tar.gz. Extracted files sit under extracted/ next to that archive. app_id is the app UUID, not the public slug.

Database​

VariableDefaultPurpose
POSTGRES_DATABASE_URLemptyPostgreSQL DSN. Unset uses SQLite
SQLITE_PATHdb.sqlite3, /app/data/db.sqlite3 in DockerSQLite file
POSTGRES_SSL_REQUIREtrue when DEBUG=falseRequire TLS to PostgreSQL. Set false for a private database without TLS

Cache and rate limits​

REDIS_URL is required when DEBUG=false. Django uses it for the rate-limit cache and for the scheduled-job broker. manage.py check --deploy reports authapi.E004 when it is missing, and the container exits before migrations with the same message. CELERY_BROKER_URL does not replace it. SCHEDULER_ENABLED=false does not replace it either.

With DEBUG=true, leave REDIS_URL unset for local development. The scheduler stays off and logs a warning. authapi.W001 still warns when production would use the in-memory cache with GUNICORN_WORKERS greater than 1. That case is already an E004 error once DEBUG=false.

REDIS_URL=redis://redis:6379/0
VariableDefaultPurpose
HOSTING_RATE_LIMIT_ENABLEDtrueTurn the limits off. Leave them on in production
HOSTING_RATE_LIMIT_DEPLOY30 per 60sPreview, create deployment, finalize, rollback
HOSTING_RATE_LIMIT_UPLOAD20 per 60sArtifact upload
HOSTING_RATE_LIMIT_DESTRUCTIVE10 per 60sApp delete
HOSTING_RATE_LIMIT_ACCESS_REQUEST10 per 300sWaitlist request

Limits key on the authenticated user, then on the client IP. See Security hardening for TRUSTED_PROXY_IPS.

CORS and HTTPS​

VariableDefaultPurpose
CORS_ALLOW_ALL_ORIGINStrueAllow browser calls from any origin
CORS_ALLOW_CREDENTIALSfalseMust stay false while all origins are allowed. That combination refuses to start
CORS_ALLOWED_ORIGINSlocal dev origins, plus extras you appendUsed when CORS_ALLOW_ALL_ORIGINS=false
CORS_ALLOW_PRIVATE_NETWORKtruePrivate Network Access preflight header
SECURE_SSL_REDIRECTon when DEBUG=falseRedirect HTTP to HTTPS
SECURE_HSTS_SECONDS31536000 when DEBUG=false, else 0HSTS max-age
SECURE_HSTS_INCLUDE_SUBDOMAINSon when DEBUG=falseInclude subdomains in HSTS
SECURE_HSTS_PRELOADfalseHSTS preload flag
SESSION_COOKIE_SECURE, CSRF_COOKIE_SECUREon when DEBUG=falseSecure flag. Secure cookies are named __Host-sessionid and __Host-csrftoken. Domain stays unset. CSRF_COOKIE_HTTPONLY is on
TRUSTED_PROXY_IPSemptyProxy IPs or CIDRs allowed to set X-Forwarded-For

API auth is the Bearer JWT, not a cookie. Permissive CORS is the default for that reason. Token delivery after login is the identity OAuth redirect allowlist, not CORS.

Gunicorn​

The image entrypoint runs migrations, check --deploy, then Gunicorn and the scheduler. See Scheduled jobs.

VariableDefaultPurpose
GUNICORN_WORKERS2Worker processes
GUNICORN_THREADS2Threads per worker
GUNICORN_TIMEOUT120Seconds before Gunicorn kills a silent worker. Sized for large uploads

Scheduled jobs​

The same container runs retry_webhooks every minute and purge_expired_data every hour at minute 17. Full behavior, the staff API, and the Prometheus series are in Scheduled jobs.

VariableDefaultPurpose
SCHEDULER_ENABLEDtruefalse keeps the Celery worker out of this container
CELERY_BROKER_URLREDIS_URLBroker for the jobs. The cache still needs REDIS_URL
CELERY_WORKER_CONCURRENCY2Threads in the worker
CELERY_BEAT_SCHEDULE_FILE/tmp/celerybeat-scheduleBeat schedule file. Losing it on restart only resets the schedule

Shellui Actions​

Webhooks do not need Redis. These variables tune delivery. The catalog and the admin API are in Webhooks.

VariableDefaultPurpose
ACTIONS_OUTBOX_MAX_ATTEMPTS8Attempts before a delivery is dead
ACTIONS_WEBHOOK_TIMEOUT_SECONDS5Timeout of one webhook POST
ACTIONS_WEBHOOK_RETRY_LEASE_SECONDS120How long one retry run holds a row
ACTIONS_WEBHOOK_DISPATCH_WORKERS4Threads used for post-commit delivery
ACTIONS_WEBHOOK_SYNC_DELIVERYfalseDeliver inside the request. Leave false outside tests
ACTIONS_WEBHOOK_ALLOW_PRIVATEsame as DEBUGAllow webhook URLs that resolve to private or loopback addresses

Email notifications​

Set EMAIL_SERVICE_API_KEY to forward hosting events to email-service. An empty key sends nothing. Webhook and email bodies omit sign-in links, tokens, and secret-shaped fields. See Email notifications.

VariableDefaultPurpose
EMAIL_SERVICE_URLhttps://email.shellui.comOrigin only. hosting-service appends /api/v1/events. Set it in every region, for example https://email.eu.shellui.com
EMAIL_SERVICE_API_KEYemptyService key (esk_). Empty disables forwarding
EMAIL_SERVICE_ALLOW_PRIVATEfalseAllow a URL that resolves to a private or loopback address

Event log​

VariableDefaultPurpose
EVENT_LOG_RETENTION_DAYS7Days to keep event-log rows and finished webhook and email deliveries

manage.py purge_expired_data deletes older rows. The container runs it every hour at minute 17. See Event log and Scheduled jobs.

Shellui MCP​

Optional tuning for POST /mcp. No variables are required for MCP to stay on. See Shellui MCP.

VariableDefaultPurpose
MCP_RATE_LIMIT_AGENT120MCP tool calls per minute per agent
HOSTING_MCP_RESOURCEemptyRFC 8707 resource identifier (aud). Defaults to {request origin}/mcp
HOSTING_PUBLIC_URLemptyPublic HTTPS origin when the MCP resource URL cannot be inferred from the request

Apex landing​

VariableDefaultPurpose
ROOT_REDIRECT_URLemptyAbsolute URL. When set, apex GET / returns 301. App subdomains are unchanged
SHELLUI_WEBSITE_URLhttps://shellui.comLink on the landing page
SHELLUI_DOCS_URLhttps://docs.shellui.comLink on the landing page
SHELLUI_PLAYGROUND_URLhttps://playground.shellui.comLink on the landing page
SHELLUI_GITHUB_URLhttps://github.com/shelluiLink on the landing page
SHELLUI_AI_URLhttps://shellui.aiLink on the landing page
HOSTING_REGIONemptyRegion label on the landing page, for example EU. Empty hides the region line

Leave ROOT_REDIRECT_URL empty when this process should show the hosting landing page. The landing page and llms.txt build their hosted URLs from HOSTING_APP_DOMAIN and HOSTING_APP_SCHEME, so each region shows its own domain. GET /llms.txt on the apex returns a short text description of the site.

Error reporting​

VariableDefaultPurpose
SENTRY_DSNemptyTurns on Sentry. No personal data is attached
SENTRY_ENVIRONMENTdevelopment or production from DEBUGSentry environment tag
SENTRY_RELEASEthe package versionSentry release tag
SENTRY_TRACES_SAMPLE_RATE0Share of requests traced. 0 reports errors only

Health check​

GET /health/live returns 200 ok before host checks, the HTTPS redirect, sessions and the database. The Docker image runs tools/healthcheck.py against http://127.0.0.1:8000/health/live as its HEALTHCHECK, so Coolify and Docker need no extra config. It does not check Postgres or Redis. In worker mode it always passes. GET /hosting/v1/health stays the detailed status endpoint.