@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
mdx 256 lines 9.06 KB
Raw
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)