Set Up Managed Services

Managed services are databases and storage systems that Temps runs as Docker containers on your server: PostgreSQL, MariaDB, Redis, MongoDB and S3-compatible storage. Nothing is provisioned for you automatically. You create a service, link it to a project, and Temps generates credentials, injects them as environment variables on the next deploy, and backs the service up to S3 on your schedule.

Available service types

Temps also provides higher-level abstractions built on these services:

PostgreSQL can also run as a pg_auto_failover cluster across several nodes; see Postgres high availability.

Create a service

From the API

curl -X POST "https://your-temps-instance/api/external-services" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-postgres",
    "service_type": "postgres",
    "parameters": {
      "port": "5432",
      "max_connections": "200"
    }
  }'

Configuration by service type

PostgreSQL:

MariaDB:

Redis:

MongoDB:

S3 / RustFS:

Link a service to a project

Linking injects the service's connection credentials as environment variables into your project's containers at deploy time.

From the API

curl -X POST "https://your-temps-instance/api/external-services/{service_id}/projects" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1
  }'

What happens when you link

1. Per-project isolation — For PostgreSQL and MariaDB, a dedicated database is created named {project_slug}_{environment_slug}. For Redis, a database number (0-15) is assigned. For S3, a dedicated bucket is created.
2. Environment variables — Connection credentials are generated using the Docker container name as the hostname (for internal networking) and injected on the next deploy.
3. One per type — Only one service of each type can be linked to a project. To switch to another instance of the same type, unlink the current one first.

Environment variables by service

If your framework expects DATABASE_URL for PostgreSQL, map it yourself, for example by reading POSTGRES_URL in your config.

Preview environment variables

To see what variables will be injected without deploying:

# Preview variable names
curl "https://your-temps-instance/api/external-services/{service_id}/preview-environment-names" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Preview with masked values
curl "https://your-temps-instance/api/external-services/{service_id}/preview-environment-masked" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get actual values for a project
curl "https://your-temps-instance/api/external-services/{service_id}/projects/{project_id}/environment" \
  -H "Authorization: Bearer YOUR_TOKEN"

Unlink a service

curl -X DELETE "https://your-temps-instance/api/external-services/{service_id}/projects/{project_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Unlinking does not delete the database or data inside the service — it only stops injecting environment variables. You can re-link later.

Import an existing container

If you already have a PostgreSQL, MariaDB (or MySQL-compatible), Redis, MongoDB or S3-compatible container running on your server, you can import it into Temps instead of creating a new one.

From the API:

# List importable containers
curl "https://your-temps-instance/api/external-services/available-containers" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Import one
curl -X POST "https://your-temps-instance/api/external-services/import" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "container_id": "abc123...",
    "name": "existing-postgres",
    "service_type": "postgres",
    "parameters": {
      "host": "localhost",
      "port": "5432",
      "database": "postgres",
      "username": "postgres",
      "password": "your-existing-password"
    }
  }'

Manage service lifecycle

Start and stop

Services can be started and stopped independently:

# Stop a service (keeps data)
curl -X POST "https://your-temps-instance/api/external-services/{id}/stop" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Start it again
curl -X POST "https://your-temps-instance/api/external-services/{id}/start" \
  -H "Authorization: Bearer YOUR_TOKEN"

Stopping a service does not delete any data — the Docker volume persists. Applications linked to a stopped service will fail to connect until the service is started again.

Health check

curl "https://your-temps-instance/api/external-services/{id}/health" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete a service

curl -X DELETE "https://your-temps-instance/api/external-services/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Upgrade a service

services upgrade (and POST /api/external-services/{id}/upgrade) swaps the Docker image within the same major version, for example from postgres:18 to gotempsh/postgres-walg:18-bookworm. A PostgreSQL major-version change through this endpoint is rejected without touching the service.

curl -X POST "https://your-temps-instance/api/external-services/{id}/upgrade" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "docker_image": "gotempsh/postgres-walg:18-bookworm"
  }'

PostgreSQL major version upgrades

For a major version (e.g. 17 to 18), open the service and choose Major Version Upgrade… from its actions menu, or call the upgrades API:

curl -X POST "https://your-temps-instance/api/external-services/{id}/upgrades" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_version": "17",
    "to_version": "18",
    "from_image": "gotempsh/postgres-walg:17-bookworm",
    "to_image": "gotempsh/postgres-walg:18-bookworm"
  }'

PostgreSQL HA clusters

A PostgreSQL service can run as a high-availability cluster instead of a single standalone container. Creating a cluster, how apps connect and its limits are covered in Postgres high availability; this section documents how cluster backups and restores work internally.

Cluster services have topology = "cluster" and service_type = "postgres", and run on the gotempsh/postgres-ha:18-bookworm-walg image. A cluster is made up of a pg_auto_failover monitor plus two or more data members tracked in the service_members table. Linked apps receive a multi-host POSTGRES_URL that lists every data member with target_session_attrs=read-write, which lands writes on the current primary. Connecting through <cluster>.temps.local names instead requires cluster DNS, which is experimental and off by default (details).

Cluster backups and restore use WAL-G physical backups (basebackup plus continuous WAL archiving). Standalone PostgreSQL services also use WAL-G when their image includes it (the default image does), and fall back to pg_dump otherwise; see Backups.

Cluster backup

When you back up a cluster (from the service's Backup button or the standard backup API), Temps routes through ExternalServiceManager::backup_postgres_cluster instead of the standalone path. That method:

1. Finds the current writable primary by asking pg_auto_failover for the member whose live state is primary or single.

2. Writes a /var/lib/postgresql/walg.env credentials file to every running data member (not the monitor). Writing it everywhere means archiving keeps working after a failover promotes a different member to primary.

3. Runs wal-g backup-push /var/lib/postgresql/pgdata against the primary to upload the basebackup to S3. WAL segments are lz4-compressed by default.

4. Enables continuous WAL archiving by running, against the primary:

   ALTER SYSTEM SET archive_command = '. /var/lib/postgresql/walg.env && wal-g wal-push %p';
   ALTER SYSTEM SET archive_mode = 'on';
   ALTER SYSTEM SET wal_level = 'replica';
   SELECT pg_reload_conf();
   

   Copy

Because archive_command is stored in postgresql.auto.conf — which is part of pgdata and is streamed to replicas — the setting survives a failover. A new primary inherits it without an operator re-running anything, so WAL keeps flowing to the same S3 prefix.

In-place cluster restore

An in-place restore of a cluster backup routes through ExternalServiceManager::restore_postgres_cluster. It first snapshots the existing member topology (names, ordinals, roles, node assignments), then runs in three phases:

Because container names derive deterministically from ordinal (postgres-<cluster>-<ordinal>), the rebuilt cluster keeps the same names, ordinals, and DNS records, so the injected connection string still works. Application connections reconnect once the cluster is back up.

Next steps

• Backups — schedule backups of every service to an S3 bucket
• Restore & Recovery — restore in place, into a new service, or to a point in time
• Deploy with a database — tutorial: create a database, link it and deploy an app that uses it