feat(docker): add Docker resources

examples/docker-postgres/README.md

@@ -0,0 +1,29 @@
+# Docker PostgreSQL Example
+
+This example provisions PostgreSQL 18 Alpine with Docker resources:
+
+- `Docker.RemoteImage` pulls `postgres:18-alpine`
+- `Docker.Network` creates an app network
+- `Docker.Volume` creates persistent database storage
+- `Docker.Container` starts PostgreSQL with a redacted password, a network alias, a named volume, and a host port
+- `Docker.inspectContainer` returns the bound host port
+
+Docker resources use the active Docker CLI context. That can be Docker Desktop, a remote Docker host, an SSH context, or a CI runner daemon.
+
+These resources are separate from `Cloudflare.Container`. The bridge between Docker and cloud container platforms is an image reference or registry digest, not a swappable container object.
+
+## Commands
+
+```sh
+bun install
+POSTGRES_PASSWORD=change-me bun run --filter docker-postgres-example deploy
+bun run --filter docker-postgres-example destroy
+```
+
+If `POSTGRES_PASSWORD` is omitted, the example generates and stores a redacted password with `Alchemy.makeRandom`.
+
+The stack publishes PostgreSQL on `localhost:15432`:
+
+```sh
+psql postgres://alchemy:change-me@localhost:15432/app
+```

examples/docker-postgres/alchemy.run.ts

@@ -0,0 +1,66 @@
+import * as Alchemy from "alchemy";
+import * as Docker from "alchemy/Docker";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+const POSTGRES_PORT = 15432;
+const POSTGRES_CONTAINER = "alchemy-example-postgres";
+
+export default Alchemy.Stack(
+  "DockerPostgresExample",
+  {
+    providers: Layer.merge(Docker.providers(), Alchemy.RandomProvider()),
+    state: Alchemy.localState(),
+  },
+  Effect.gen(function* () {
+    const configuredPassword = yield* Config.redacted("POSTGRES_PASSWORD").pipe(
+      Config.option,
+    );
+    const password = yield* Option.match(configuredPassword, {
+      onSome: Effect.succeed,
+      onNone: () => Alchemy.makeRandom("PostgresPassword", { bytes: 16 }),
+    });
+
+    const image = yield* Docker.RemoteImage("postgres-image", {
+      name: "postgres",
+      tag: "18-alpine",
+      alwaysPull: false,
+    });
+    const network = yield* Docker.Network("app-network");
+    const data = yield* Docker.Volume("postgres-data");
+
+    const postgres = yield* Docker.Container("postgres", {
+      name: POSTGRES_CONTAINER,
+      image,
+      environment: {
+        POSTGRES_DB: "app",
+        POSTGRES_USER: "alchemy",
+        POSTGRES_PASSWORD: password,
+      },
+      ports: [{ external: POSTGRES_PORT, internal: 5432 }],
+      volumes: [
+        {
+          hostPath: data.name,
+          containerPath: "/var/lib/postgresql/data",
+        },
+      ],
+      networks: [{ name: network.name, aliases: ["postgres"] }],
+      healthcheck: {
+        cmd: ["CMD-SHELL", "pg_isready -U alchemy -d app"],
+        interval: "5 seconds",
+        timeout: "5 seconds",
+        retries: 10,
+      },
+      start: true,
+    });
+    return {
+      container: postgres.name,
+      image: image.imageRef,
+      network: network.name,
+      volume: data.name,
+      hostPort: postgres.ports,
+    };
+  }),
+);

examples/docker-postgres/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "docker-postgres-example",
+  "version": "0.0.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alchemy-run/alchemy-effect.git",
+    "directory": "examples/docker-postgres"
+  },
+  "type": "module",
+  "scripts": {
+    "deploy": "alchemy deploy",
+    "destroy": "alchemy destroy"
+  },
+  "dependencies": {
+    "alchemy": "workspace:*",
+    "effect": "catalog:"
+  }
+}

examples/docker-postgres/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["alchemy.run.ts"],
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".",
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "target": "ESNext"
+  },
+  "references": [
+    {
+      "path": "../../packages/alchemy/tsconfig.json"
+    }
+  ]
+}

packages/alchemy/package.json

@@ -115,6 +115,12 @@
       "worker": "./src/Bundle/index.ts",
       "import": "./lib/Bundle/index.js"
     },
+    "./Docker": {
+      "types": "./lib/Docker/index.d.ts",
+      "bun": "./src/Docker/index.ts",
+      "worker": "./src/Docker/index.ts",
+      "import": "./lib/Docker/index.js"
+    },
     "./ContentType": {
       "types": "./lib/ContentType.d.ts",
       "bun": "./src/ContentType.ts",

packages/alchemy/src/AWS/ECS/Task.ts

@@ -11,17 +11,12 @@ import * as Stream from "effect/Stream";
 import type * as rolldown from "rolldown";
 import { AlchemyContext } from "../../AlchemyContext.ts";
 import * as Bundle from "../../Bundle/Bundle.ts";
-import {
-  dockerBuild,
-  materializeDockerfile,
-  pushImage,
-  writeContextFiles,
-} from "../../Bundle/Docker.ts";
 import {
   findCwdForBundle,
   getStableContextDir,
 } from "../../Bundle/TempRoot.ts";
 import { isResolved } from "../../Diff.ts";
+import { Docker } from "../../Docker/Docker.ts";
 import * as Output from "../../Output.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import { Platform, type Main, type PlatformProps } from "../../Platform.ts";
@@ -345,6 +340,7 @@ export const TaskProvider = () =>
     Task,
     Effect.gen(function* () {
       const stack = yield* Stack;
+      const docker = yield* Docker;
 
       const { dotAlchemy } = yield* AlchemyContext;
       const fs = yield* FileSystem.FileSystem;
@@ -724,15 +720,16 @@ await Effect.runPromise(program);
         );
         const registry = credentials.proxyEndpoint.replace(/^https?:\/\//, "");
 
-        yield* materializeDockerfile(dockerfile, contextDir);
-        yield* writeContextFiles(contextDir, [
-          { path: "index.mjs", content: code },
-        ]);
-        yield* dockerBuild({
+        yield* docker.materialize({
+          context: contextDir,
+          dockerfile: dockerfile,
+          files: [{ path: "index.mjs", content: code }],
+        });
+        yield* docker.image.build({
           tag: imageUri,
           context: contextDir,
         });
-        yield* pushImage(imageUri, {
+        yield* docker.image.push(imageUri, {
           username: "AWS",
           password,
           server: registry,

packages/alchemy/src/AWS/Providers.ts

@@ -18,6 +18,7 @@ import * as Schedule from "effect/Schedule";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
 import * as Command from "../Command/index.ts";
+import { DockerLive } from "../Docker/Docker.ts";
 import { KeyPair, KeyPairProvider } from "../KeyPair.ts";
 import * as Provider from "../Provider.ts";
 import { Random, RandomProvider } from "../Random.ts";
@@ -342,6 +343,7 @@ export const providers = () =>
         KeyPairProvider(),
         RandomProvider(),
         Assets.AssetsLive,
+        DockerLive,
       ),
     ),
     Layer.provideMerge(Region.fromEnvironment),