Self-Host Configuration

Start from .env.example and keep production secrets out of source control.

Important groups

Routing and basemap build creation also requires VALHALLA_BUILDER_IMAGES and PLANETILER_BUILDER_IMAGES. Each value is a comma-separated operator allowlist of canonical registry/repository@sha256:<digest> references. The first image is selected for new jobs; Console and API callers cannot override it.

When the self-host supervisor is enabled, set SUPERVISOR_COMPOSE_PROFILES to the comma-separated profiles it must upgrade, including with-supervisor and every profile with running services. Release manifests must exactly cover the resulting Compose service set.

Outbound URLs resolve and pin DNS before the connection is opened. Private destinations are denied unless their exact hostname, IP address, or CIDR is listed in the comma-separated OUTBOUND_PRIVATE_ALLOWLIST. Configure the same allowlist independently on external root agents that must download from private sources. The legacy broad ALLOW_PRIVATE_SOURCE_URLS=true setting now requires an explicit allowlist and otherwise prevents startup. | Worker processing | concurrency, outbox polling, DuckDB, Tippecanoe, ogr2ogr, Overture release settings | | Managed providers | Dodo Payments and ZeptoMail settings |

Deployment mode

Use self-host mode for Docker Compose, VPS platforms, and customer-managed environments:

DEPLOYMENT_MODE=self_host

Use managed mode only for a managed Planisfy environment with production provider configuration:

DEPLOYMENT_MODE=managed

See deployment modes.

Public URLs

Make sure public URLs match the domains clients will use:

NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_URL=https://console.example.com
NEXT_PUBLIC_CONSOLE_URL=https://console.example.com
NEXT_PUBLIC_DOCS_URL=https://docs.example.com
NEXT_PUBLIC_MARKETING_URL=https://example.com

For local Docker Compose, keep the localhost defaults from .env.example.

Storage

Self-host deployments should default to S3-compatible storage:

STORAGE_PROVIDER=s3
S3_BUCKET=planisfy-artifacts
S3_REGION=auto
S3_ENDPOINT=http://localhost:9000
CONTAINER_S3_ENDPOINT=http://minio:9000
S3_PUBLIC_URL=http://localhost:9000/planisfy-artifacts
AWS_ACCESS_KEY_ID=planisfy
AWS_SECRET_ACCESS_KEY=planisfy-local-minio-password

S3_ENDPOINT is host-visible. CONTAINER_S3_ENDPOINT is used by containers on the Compose network.

STORAGE_PROVIDER=local writes to the local filesystem and is useful for development or small smoke tests. It cannot issue signed direct upload sessions, so it is not appropriate for regional or planet-scale routing artifacts.

Geospatial services

The API can start when map engines are degraded, but service APIs need configured backends:

• Geocoding needs PELIAS_INTERNAL_URL.
• Routing needs VALHALLA_INTERNAL_URL and compatible graph data.
• Tiles and glyphs need Martin sources and fonts.
• Elevation needs ELEVATION_INTERNAL_URL and DEM files.
• Static maps need STATIC_RENDERER_INTERNAL_URL.

Review data sources before testing clients.

Billing and email providers

Dodo Payments settings are required for managed hosted checkout. In self-host mode they can remain empty unless you are building a custom billing integration outside the built-in hosted checkout flow.

Email/password authentication is disabled by default. Enable it explicitly with:

NEXT_PUBLIC_AUTH_EMAIL_PASSWORD_ENABLED=true

When enabled, ZEPTOMAIL_SEND_MAIL_TOKEN and ZEPTOMAIL_FROM_AUTH are mandatory so signup verification and password recovery cannot lead to unusable accounts. Keep the flag false for OAuth-only deployments. At least one complete GitHub or Google provider must then be configured.

ZEPTOMAIL_FROM_NOTIFICATIONS is additionally required for managed transactional notifications. Existing password-based installations must configure the flag and auth sender before upgrading.

Related

• Docker Compose
• Data sources
• Production best practices