Deployment

The Neon repository is the source for the open-source storage stack and the neon Postgres extension. There is no production deployment manifest checked in — that lives in a separate cloud infrastructure repository — but the build artifacts and operator-facing documentation that go into deployments are here.

This page collects what's relevant for someone bringing up Neon outside of the production Neon Cloud.

Artifacts produced by the build

make produces:

• Binaries under target/<profile>/:
  • pageserver
  • safekeeper
  • storage_broker
  • storage_controller
  • storage_scrubber
  • proxy, local_proxy
  • compute_ctl
  • endpoint_storage
  • pagectl (offline diagnostic)
  • storcon-cli
  • neon_local
• Postgres installed under pg_install/v{14,15,16,17}/ with bin/postgres and the neon extension .so files.
• Static walproposer library for FFI from C into the safekeeper sim tests.

Container images

Two Dockerfiles are checked in:

File	Builds
Dockerfile (root)	Generic image used to build storage-side binaries (pageserver/safekeeper/etc).
compute/compute-node.Dockerfile	Production compute image, ~90 KB of build steps including a curated set of extensions.

The release-cut workflow uses these to push to Neon's container registry. See .github/workflows/release-storage.yml, release-proxy.yml, release-compute.yml, and _push-to-container-registry.yml.

docker-compose/ has a few compose files for local multi-service setups (proxy + Postgres + Redis, compute + pageserver + safekeeper, etc.) used by integration tests.

Required infrastructure for a self-hosted deployment

docs/storage_controller.md has the most detail. The minimum:

Component	Storage requirements
Storage controller	A durable Postgres database (≥1 CPU, ≥1 GB RAM). Must not be ephemeral — losing this loses generation numbers.
Pageservers	Local NVMe-class storage for hot layer files. Local disk is a cache; data is durably in object storage.
Safekeepers	Durable local storage for the WAL ring. Three-node quorum is the typical configuration.
Object storage	S3-compatible bucket, Azure Blob container, GCS bucket, or any combination.
Storage broker	Stateless. One or more instances behind a load balancer.
Compute	Built from the compute/compute-node.Dockerfile image. compute_ctl requires HTTP access to the storage controller and an assigned pageserver.
Proxy	Stateless. Needs Redis for cross-instance cancellation routing.

Configuration

Each binary takes a TOML config file. The canonical examples in this repo are the ones that cargo neon init produces in .neon/:

• pageserver.toml — pageserver/src/config.rs is the schema (~36 KB).
• safekeeper.toml (or CLI flags) — safekeeper/src/lib.rs and friends.
• storage_controller is mostly CLI-flag-driven; --config-file is supported but rarely used.
• proxy is CLI-flag-driven.

docs/settings.md documents many of the production tunables.

For tunable details see Reference / Configuration.

CI/CD in this repo

The CI pipeline (.github/workflows/build_and_test.yml) builds and tests every PR. Release pipelines (release-storage.yml, release-proxy.yml, release-compute.yml) cut a versioned release of the corresponding component(s) and push images.

pin-build-tools-image.yml updates the pinned build-tools image hash that CI uses; that image is built from build-tools/Dockerfile.

Schema migrations

The storage controller's metadata DB has migrations under storage_controller/migrations/. They're baked into the binary and applied at startup. To author a new migration, see Storage controller / migrations.

compute_tools/src/migrations/ holds catalog-level SQL migrations applied to every Neon compute on start.

Generation safety

The single most operationally important invariant is that generation numbers never go backwards. They're held in the storage controller's metadata DB. The repo's deployment recommendations:

• Use a managed Postgres for the controller DB (RDS, Cloud SQL, etc.).
• Take regular backups.
• Multiple controller instances for HA, electing a leader via storage_controller/src/leadership.rs.

Operational tooling

• pagectl (pageserver/ctl/) — offline tool. Inspect layer files. Useful when responding to "this tenant looks corrupted" tickets.
• storcon-cli (control_plane/storcon_cli/) — talk to a running storage controller. Migrate shards, drain a node, mark offline.
• storage_scrubber — list/delete orphan objects in cloud storage.
• cargo neon — local-only; not for production.

Observability

All Rust services emit:

• JSON-formatted logs to stderr (libs/tracing-utils/).
• Prometheus metrics on GET /metrics over HTTP.
• OTLP traces if OTEL_EXPORTER_OTLP_ENDPOINT is set.

There are no canonical Grafana dashboards in this repo, but the metric names are stable enough that you can build them — see pageserver/src/metrics.rs (~170 KB of definitions).

For more, see How to monitor.

See also

• Architecture
• Services
• Storage controller — has the deployment-specific notes.
• docs/storage_controller.md and docs/settings.md.