The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | --- |
| 2 | title: "Local services: Postgres with containers, networks, and volumes" |
| 3 | description: Run a local Postgres for development as alchemy resources — a pinned image, a named network and volume, a Redacted password, and a healthchecked container that converges on every deploy. |
| 4 | --- |
| 5 | |
| 6 | A Docker `Container` runs an image; a `Network` gives containers a |
| 7 | stable DNS name to reach each other; a `Volume` keeps data alive |
| 8 | across container replacements; a `RemoteImage` pins exactly which |
| 9 | image you run. In alchemy all four are resources in your Stack, so |
| 10 | your local dev dependencies get the same treatment as your cloud |
| 11 | infrastructure: a reviewable diff on every change, one deploy that |
| 12 | converges Docker to the declared state, and one destroy that tears |
| 13 | it all down. |
| 14 | |
| 15 | You'll need a Docker daemon reachable from your CLI and the provider |
| 16 | registered — see [Setup](/docker/setup) and the |
| 17 | [Docker overview](/docker). The full program below is the checked-in |
| 18 | [`examples/docker-postgres`](https://github.com/alchemy-run/alchemy/tree/main/examples/docker-postgres). |
| 19 | |
| 20 | ## Pin the image |
| 21 | |
| 22 | ```typescript |
| 23 | import * as Alchemy from "alchemy"; |
| 24 | import * as Docker from "@alchemy.run/docker"; |
| 25 | import * as Effect from "effect/Effect"; |
| 26 | import * as Layer from "effect/Layer"; |
| 27 | |
| 28 | export default Alchemy.Stack( |
| 29 | "DockerPostgresExample", |
| 30 | { |
| 31 | providers: Layer.merge(Docker.providers(), Alchemy.RandomProvider()), |
| 32 | state: Alchemy.localState(), |
| 33 | }, |
| 34 | Effect.gen(function* () { |
| 35 | const image = yield* Docker.RemoteImage("postgres-image", { |
| 36 | name: "postgres", |
| 37 | tag: "18-alpine", |
| 38 | alwaysPull: false, |
| 39 | }); |
| 40 | // ... |
| 41 | }), |
| 42 | ); |
| 43 | ``` |
| 44 | |
| 45 | `RemoteImage` pulls `postgres:18-alpine` through your Docker CLI, |
| 46 | and `alwaysPull: false` pins it — once the image is present locally, |
| 47 | subsequent deploys diff to a no-op instead of re-pulling on every |
| 48 | run. The Stack uses `Alchemy.localState()` because there's no cloud |
| 49 | account behind these resources, and merges in |
| 50 | `Alchemy.RandomProvider()` for the generated password below. |
| 51 | |
| 52 | ## A network and a volume |
| 53 | |
| 54 | ```typescript |
| 55 | const network = yield* Docker.Network("app-network"); |
| 56 | const data = yield* Docker.Volume("postgres-data"); |
| 57 | ``` |
| 58 | |
| 59 | Neither needs any props — the engine generates unique physical names |
| 60 | from the app, stage, and logical ID. Note that changing a `Network` |
| 61 | or `Volume` prop (driver, labels, IPv6) is a replacement: the old |
| 62 | one is deleted and a new one created, so treat a Volume's props as |
| 63 | fixed once it holds data you care about. |
| 64 | |
| 65 | ## A Redacted password |
| 66 | |
| 67 | ```typescript |
| 68 | import * as Config from "effect/Config"; |
| 69 | import * as Option from "effect/Option"; |
| 70 | |
| 71 | const configuredPassword = yield* Config.Redacted("POSTGRES_PASSWORD").pipe( |
| 72 | Config.option, |
| 73 | ); |
| 74 | const password = yield* Option.match(configuredPassword, { |
| 75 | onSome: Effect.succeed, |
| 76 | onNone: () => Alchemy.makeRandom("PostgresPassword", { bytes: 16 }), |
| 77 | }); |
| 78 | ``` |
| 79 | |
| 80 | If `POSTGRES_PASSWORD` is set in the environment it's used as-is; |
| 81 | otherwise `Alchemy.makeRandom` generates a stable random secret |
| 82 | (this is what `RandomProvider` in the Stack config is for). Either |
| 83 | way the value is `Redacted`, and `Container` passes environment |
| 84 | values to the daemon via the process environment — only the keys |
| 85 | appear on the `docker` argv, so the secret never lands in shell |
| 86 | history or a process listing. |
| 87 | |
| 88 | ## The container |
| 89 | |
| 90 | ```typescript |
| 91 | const postgres = yield* Docker.Container("postgres", { |
| 92 | name: "alchemy-example-postgres", |
| 93 | image, |
| 94 | environment: { |
| 95 | POSTGRES_DB: "app", |
| 96 | POSTGRES_USER: "alchemy", |
| 97 | POSTGRES_PASSWORD: password, |
| 98 | }, |
| 99 | ports: [{ external: 15432, internal: 5432 }], |
| 100 | volumes: [ |
| 101 | { hostPath: data.name, containerPath: "/var/lib/postgresql/data" }, |
| 102 | ], |
| 103 | networks: [{ name: network.name, aliases: ["postgres"] }], |
| 104 | healthcheck: { |
| 105 | cmd: ["CMD-SHELL", "pg_isready -U alchemy -d app"], |
| 106 | interval: "5 seconds", |
| 107 | timeout: "5 seconds", |
| 108 | retries: 10, |
| 109 | }, |
| 110 | start: true, |
| 111 | }); |
| 112 | ``` |
| 113 | |
| 114 | `image` accepts the `RemoteImage` resource directly — no manual ref |
| 115 | plumbing. A `hostPath` set to a volume's name mounts the named |
| 116 | volume rather than a host directory, the `postgres` network alias |
| 117 | gives other containers on `app-network` a stable DNS name, the |
| 118 | healthcheck intervals take Effect `Duration` strings like |
| 119 | `"5 seconds"`, and `start: true` actually runs the container |
| 120 | (the default creates it stopped). |
| 121 | |
| 122 | ## Read the bound ports |
| 123 | |
| 124 | ```typescript |
| 125 | // as Stack outputs: |
| 126 | return { container: postgres.name, hostPort: postgres.ports }; |
| 127 | |
| 128 | // or live, from any Effect with the Docker provider: |
| 129 | const runtime = yield* Docker.inspectContainer("alchemy-example-postgres"); |
| 130 | ``` |
| 131 | |
| 132 | The container's `ports` attribute is a record keyed by container |
| 133 | port and protocol — here `"5432/tcp"` maps to `15432` — which is |
| 134 | what your app's connection string needs; `Docker.inspectContainer` |
| 135 | reads the same normalized attributes fresh from the daemon for any |
| 136 | container by name, bound host ports included. |
| 137 | |
| 138 | The following examples show optional runtime controls on separate |
| 139 | worker containers. Check your image's filesystem and user requirements |
| 140 | before applying them to the Postgres container above. |
| 141 | |
| 142 | ## Limit memory, CPU, and processes |
| 143 | |
| 144 | ```typescript |
| 145 | const worker = yield* Docker.Container("worker", { |
| 146 | image: "alpine:3.22", |
| 147 | command: ["sleep", "3600"], |
| 148 | memory: "256m", |
| 149 | memorySwap: "256m", |
| 150 | memoryReservation: "128m", |
| 151 | cpus: 0.5, |
| 152 | pidsLimit: 128, |
| 153 | start: true, |
| 154 | }); |
| 155 | ``` |
| 156 | |
| 157 | `memory` is a hard RAM limit; `memoryReservation` is a soft |
| 158 | limit under contention. `memorySwap` limits **RAM plus swap**, not |
| 159 | swap alone. Setting it equal to `memory` disables swap for this |
| 160 | container where supported. `cpus: 0.5` limits CPU time to half |
| 161 | a core, and `pidsLimit` limits the number of processes and threads. |
| 162 | These limits apply to ordinary Docker Engine containers, not Swarm |
| 163 | services. |
| 164 | |
| 165 | ## Restrict privileges and writable paths |
| 166 | |
| 167 | ```typescript |
| 168 | const worker = yield* Docker.Container("restricted-worker", { |
| 169 | image: "alpine:3.22", |
| 170 | command: ["sleep", "3600"], |
| 171 | readOnlyRootFilesystem: true, |
| 172 | capDrop: ["ALL"], |
| 173 | noNewPrivileges: true, |
| 174 | user: "1000:1000", |
| 175 | init: true, |
| 176 | tmpfs: [{ path: "/tmp", size: "32m", mode: 0o1777 }], |
| 177 | start: true, |
| 178 | }); |
| 179 | ``` |
| 180 | |
| 181 | `readOnlyRootFilesystem` is Alchemy's name for Docker's `--read-only`: |
| 182 | writeable directories must be mounted separately. The `tmpfs` |
| 183 | above provides ephemeral scratch space; use a named `Volume` for |
| 184 | data that must survive replacement. `capDrop: ["ALL"]` removes |
| 185 | Linux capabilities, `noNewPrivileges` prevents gaining privileges |
| 186 | through exec, and `user` sets the runtime UID/GID. `init` handles |
| 187 | signal forwarding and reaping child processes. Only grant the |
| 188 | capabilities and filesystem access your image actually requires. |
| 189 | |
| 190 | ## Configure host security profiles |
| 191 | |
| 192 | ```typescript |
| 193 | const worker = yield* Docker.Container("profiled-worker", { |
| 194 | image: "alpine:3.22", |
| 195 | seccompProfile: "./security/worker-seccomp.json", |
| 196 | appArmorProfile: "worker-profile", |
| 197 | }); |
| 198 | ``` |
| 199 | |
| 200 | `seccompProfile` points to a JSON file on the machine running |
| 201 | Alchemy's Docker CLI. Alchemy hashes its **contents**, so editing |
| 202 | the file recreates the container even when its path stays the |
| 203 | same. `appArmorProfile` names an AppArmor policy that must already |
| 204 | be loaded on the Docker host; its availability is host-dependent. |
| 205 | Docker's default confinement applies when you leave these settings |
| 206 | unset. Avoid `"unconfined"` unless disabling a policy is intentional. |
| 207 | |
| 208 | You can also provide `groupAdd: ["2000"]` for supplementary groups |
| 209 | and `ulimits: { nofile: { soft: 1024, hard: 4096 } }` for per-process |
| 210 | limits. `userNamespace` selects a user-namespace mode; `userNamespace: "host"` |
| 211 | **opts out of** daemon user remapping rather than strengthening |
| 212 | isolation. |
| 213 | |
| 214 | ## Rotate logs and control shutdown |
| 215 | |
| 216 | ```typescript |
| 217 | const worker = yield* Docker.Container("logged-worker", { |
| 218 | image: "alpine:3.22", |
| 219 | logDriver: "local", |
| 220 | logOptions: { "max-size": "10m", "max-file": "3" }, |
| 221 | oomScoreAdjustment: 200, |
| 222 | stopSignal: "SIGTERM", |
| 223 | stopTimeout: "15 seconds", |
| 224 | }); |
| 225 | ``` |
| 226 | |
| 227 | `logDriver` and `logOptions` configure Docker-managed logging; |
| 228 | supported options depend on the selected driver. `oomScoreAdjustment` |
| 229 | adjusts Linux's preference for choosing a process under memory |
| 230 | pressure; it does **not** disable the OOM killer. `stopSignal` |
| 231 | selects the graceful-stop signal, and `stopTimeout` sets the |
| 232 | grace period before Docker forces termination. |
| 233 | |
| 234 | Changing these create-time settings replaces a managed container. |
| 235 | Replacement is **delete-first**, so account for downtime and keep |
| 236 | persistent data in volumes. Unset options preserve Docker defaults; |
| 237 | invalid combinations such as `memorySwap` without `memory` fail |
| 238 | validation before container creation. See the |
| 239 | [Container API reference](/providers/docker/container) for all |
| 240 | properties and their types. |
| 241 | |
| 242 | ## Where next |
| 243 | |
| 244 | - [Build & push an image](/docker/build-and-push) — build your own |
| 245 | image from a Dockerfile and push it to a registry. |
| 246 | - [Docker overview](/docker) — all Docker resources at a glance, |
| 247 | including how adoption of pre-existing containers, networks, and |
| 248 | volumes is gated behind `adopt`. |
| 249 | |
| 250 | Reference: |
| 251 | |
| 252 | - [Container API reference](/providers/docker/container) |
| 253 | - [RemoteImage API reference](/providers/docker/remoteimage) |
| 254 | - [Image API reference](/providers/docker/image) |
| 255 | - [Network API reference](/providers/docker/network) |
| 256 | - [Volume API reference](/providers/docker/volume) |