@dmgnr/kuber 1.0.0 → 1.2.0

package/README.md

@@ -37,6 +37,10 @@ Not required locally:
 
 Docker is not required because builds happen on the remote builder after `kuber` syncs your repo state there. `kubectl` is not required because cluster access is handled through the bundled Kubernetes client.
 
+## Next.js Example
+
+[`example/`](example/) contains a documented deployment template for adding kuber to an existing Bun-powered Next.js project without initializing or bundling an application in this repository. It includes a standalone-output Dockerfile, `.dockerignore`, `compose.yml`, and the required Next.js configuration.
+
 ## Running
 
 During development:
@@ -63,6 +67,17 @@ bun run index.ts start
 bun run index.ts stop
 bun run index.ts restart
 bun run index.ts db ls
+bun run index.ts s3 ls
+bun run index.ts s3 creds app
+bun run index.ts s3 ui app
+```
+
+All commands accept `--config` to use a configuration file other than
+`.kuberrc.ts`:
+
+```bash
+kuber --config deploy/production.kuberrc.ts up
+kuber up --config deploy/production.kuberrc.ts
 ```
 
 ### Shell Completion
@@ -90,6 +105,64 @@ For a permanent setup, write the generated script to a file and source it from y
 - `exec <deployment> <command...>`: execute a command inside a running deployment pod
 - `db ls`: list managed Postgres claims declared in the current Compose file
 - `db creds <service>`: print the generated connection details for a managed Postgres claim
+- `s3 ls`: list managed S3 claims declared in the current Compose file
+- `s3 creds <service>`: print all generated S3 environment variables for a service
+- `s3 ui <service>`: print the Garage UI object-browser URL for a service bucket
+
+## Configuration
+
+Kuber optionally loads `.kuberrc.ts` from the working directory. The file must
+default export an object satisfying the published `KuberConfig` type:
+
+```ts
+import type { KuberConfig } from "@dmgnr/kuber";
+
+export default {
+  project: "my-app",
+  composeFile: "compose.production.yml",
+  registry: "registry.example.com",
+  builders: {
+    amd64: "kuber@amd-builder",
+    arm64: "kuber@arm-builder",
+    remoteRoot: "kuber-build",
+  },
+  rolloutTimeoutMs: 10 * 60_000,
+
+  async compose(compose) {
+    const app = compose.services?.app;
+    if (app && !Array.isArray(app.environment)) {
+      app.environment ??= {};
+      app.environment.NEXT_PUBLIC_BUILD_ID =
+        await Bun.$`git rev-parse --short HEAD`
+          .text()
+          .then((value) => value.trim());
+    }
+  },
+} satisfies KuberConfig;
+```
+
+Operational defaults:
+
+- `project`: current working directory name
+- `composeFile`: the first recognized Compose filename in the working directory
+- `registry`: `registry.neko-piranha.ts.net`
+- `builders.amd64`: `kuber@astral-th`
+- `builders.arm64`: `kuber@astral`
+- `builders.remoteRoot`: `kuber-build`
+- `rolloutTimeoutMs`: `300000`
+
+Configuration hooks can be synchronous or asynchronous and receive mutable
+values:
+
+- `compose(compose, context)`: once after parsing and validation; affects every command that reads Compose
+- `preBuild(compose, context)`: before build eligibility is evaluated when builds are enabled
+- `postBuild(result, context)`: after images are built; `result` contains `built` and `changed` service names
+- `postRender(resources, context)`: after rendering and before reconciliation planning; also runs for `export`
+- `postApply(resources, context)`: after desired resources are successfully applied
+
+Hook context contains the resolved `cwd`, `project`, `composeFile`, and optional
+`configFile`. A hook error aborts the command and is reported by the normal CLI
+error handler.
 
 ## Compose Conventions
 
@@ -188,6 +261,18 @@ The Garage operator generates the credentials. `kuber` reads its generated Secre
 
 One service can declare both `postgresql:...` and `s3:...`; all generated values are merged into the same service Secret. Managed Garage buckets and keys are retained by normal `down` and deleted by `down -f`.
 
+Inspect a claim, print its generated credentials, or get its Garage UI URL:
+
+```bash
+kuber s3 ls
+kuber s3 creds app
+kuber s3 ui app
+```
+
+`s3 creds` prints `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,
+`AWS_ENDPOINT_URL_S3`, `AWS_REGION`, and `S3_BUCKET` as shell-style environment
+assignments. `s3 ui` only prints the URL; it does not open a browser.
+
 ### Environment Files
 
 `env_file` entries are read locally and turned into a Kubernetes `Secret` named `<service>-env`. Deployments then consume that secret through `envFrom`.