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: Getting Started |
| 3 | description: A complete quickstart for a Git host protected by a shared credential. Deploy it to Cloudflare, push a repository, and clone it back. |
| 4 | --- |
| 5 | |
| 6 | import PackageManagers from "../../../components/PackageManagers.astro"; |
| 7 | |
| 8 | For a step-by-step explanation, start with [Push your first repository](/git/tutorial/part-1). |
| 9 | This page provides a complete host protected by one shared credential. |
| 10 | |
| 11 | You need a Cloudflare account with Workers, Durable Objects, and R2 |
| 12 | enabled. [Cloudflare setup](/cloudflare/setup) connects one. |
| 13 | |
| 14 | ## Install |
| 15 | |
| 16 | <PackageManagers add="alchemy @alchemy.run/cloudflare @alchemy.run/git effect" /> |
| 17 | |
| 18 | ## Define the host |
| 19 | |
| 20 | ```typescript |
| 21 | // src/git.ts |
| 22 | import * as Alchemy from "alchemy"; |
| 23 | import * as Cloudflare from "@alchemy.run/cloudflare"; |
| 24 | import * as Git from "@alchemy.run/git"; |
| 25 | import * as Effect from "effect/Effect"; |
| 26 | import * as Layer from "effect/Layer"; |
| 27 | import * as HttpRouter from "effect/http/HttpRouter"; |
| 28 | import * as Http from "alchemy/Http"; |
| 29 | import * as Redacted from "effect/Redacted"; |
| 30 | import * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 31 | import * as HttpApiBuilder from "effect/http-api/HttpApiBuilder"; |
| 32 | import * as HttpApiSecurity from "effect/http-api/HttpApiSecurity"; |
| 33 | |
| 34 | export const GitObjects = Cloudflare.R2.Bucket("GitObjects"); |
| 35 | export const GitSecret = Effect.gen(function* () { |
| 36 | const Random = yield* Alchemy.Random; |
| 37 | return yield* Random("GitSecret"); |
| 38 | }); |
| 39 | |
| 40 | /** One shared secret, sent as the password of HTTP Basic. */ |
| 41 | export const Authentication = HttpRouter.middleware( |
| 42 | Effect.gen(function* () { |
| 43 | const secret = yield* (yield* GitSecret).text; |
| 44 | return (httpEffect) => |
| 45 | Effect.gen(function* () { |
| 46 | const { password } = yield* HttpApiBuilder.securityDecode(HttpApiSecurity.basic); |
| 47 | if (Redacted.value(password) === Redacted.value(yield* secret)) { |
| 48 | return yield* httpEffect; |
| 49 | } |
| 50 | return HttpServerResponse.empty({ |
| 51 | status: 401, |
| 52 | headers: { "www-authenticate": 'Basic realm="git"' }, |
| 53 | }); |
| 54 | }).pipe(Effect.provide(Alchemy.RuntimeContext.phantom)); |
| 55 | }), |
| 56 | ); |
| 57 | |
| 58 | const GitLive = Layer.mergeAll( |
| 59 | Git.ApiLive.pipe(Layer.provide(Authentication.layer)), |
| 60 | Git.InternalApiLive, |
| 61 | ).pipe( |
| 62 | Layer.provide(Git.ApiHandlersLive), |
| 63 | Layer.provide(Git.ReposDurableObject), |
| 64 | Layer.provide(Git.RegistryDurableObject), |
| 65 | Layer.provide(Git.HasherInline), |
| 66 | Layer.provide(Git.BlobStoreR2(GitObjects)), |
| 67 | Layer.provide(Http.Platform), |
| 68 | ); |
| 69 | |
| 70 | export default class GitHost extends Cloudflare.Worker<GitHost>()( |
| 71 | "Git", |
| 72 | { main: import.meta.url, ...Git.GIT_WORKER_OPTIONS }, |
| 73 | Effect.gen(function* () { |
| 74 | const fetch = yield* HttpRouter.toHttpEffect(GitLive); |
| 75 | return { fetch }; |
| 76 | }).pipe(Effect.provide(Cloudflare.R2.ReadWriteBucketBinding)), |
| 77 | ) {} |
| 78 | ``` |
| 79 | |
| 80 | `Git.ApiLive` registers the public Git routes on the application's router. |
| 81 | `Git.ApiHandlersLive` supplies their shared implementation. `Git.InternalApiLive` |
| 82 | registers the internal hash route outside application authentication. |
| 83 | Your application chooses its server, middleware, platform, and CORS policy. |
| 84 | |
| 85 | The engine holds no users and no credentials. Who may call a route is |
| 86 | decided by the middleware applied to its route layer, and `Git.ApiLive` |
| 87 | registers every git route: the REST plane, the git wire, the raw reads, |
| 88 | and the GitHub facade. The smallest thing that secures a fresh host is |
| 89 | one shared secret. A request that presents it may do anything; any |
| 90 | other request is refused with a `401` that makes `git` ask for a |
| 91 | password. The secret is an `Alchemy.Random`, minted on the first deploy |
| 92 | and stable after it. `GIT_WORKER_OPTIONS` sets the compatibility flags |
| 93 | and the CPU limit a push needs. |
| 94 | |
| 95 | Add the host to your stack. The `Random` is a resource like any other, |
| 96 | so the stack can output its value: |
| 97 | |
| 98 | ```typescript |
| 99 | // alchemy.run.ts |
| 100 | import * as Alchemy from "alchemy"; |
| 101 | import * as Cloudflare from "@alchemy.run/cloudflare"; |
| 102 | import * as Output from "alchemy/Output"; |
| 103 | import * as Effect from "effect/Effect"; |
| 104 | import * as Redacted from "effect/Redacted"; |
| 105 | import GitHost, { GitSecret } from "./src/git.ts"; |
| 106 | |
| 107 | export default Alchemy.Stack( |
| 108 | "GitService", |
| 109 | { providers: Cloudflare.providers(), state: Cloudflare.state() }, |
| 110 | Effect.gen(function* () { |
| 111 | const git = yield* GitHost; |
| 112 | const secret = yield* GitSecret; |
| 113 | return { |
| 114 | url: git.url.as<string>(), |
| 115 | secret: Output.map(secret.text, Redacted.value), |
| 116 | }; |
| 117 | }), |
| 118 | ); |
| 119 | ``` |
| 120 | |
| 121 | ## Deploy |
| 122 | |
| 123 | <PackageManagers run="alchemy deploy" /> |
| 124 | |
| 125 | The stack prints the Worker's URL and the secret. The rest of this page |
| 126 | calls them `$HOST` and `$GIT_SECRET`: |
| 127 | |
| 128 | ```sh |
| 129 | export HOST=... |
| 130 | export GIT_SECRET=... |
| 131 | ``` |
| 132 | |
| 133 | ## Create a repository |
| 134 | |
| 135 | Repositories are named `owner/name`. The owner is a name you choose; |
| 136 | with one shared secret there are no users behind it: |
| 137 | |
| 138 | ```sh |
| 139 | curl -u "x:$GIT_SECRET" -X POST "$HOST/api/v1/repos" \ |
| 140 | -H "Content-Type: application/json" \ |
| 141 | -d '{"owner":"acme","name":"web"}' |
| 142 | ``` |
| 143 | |
| 144 | ## Push |
| 145 | |
| 146 | Use the full `$HOST` URL from the deployment output. When Git prompts, enter |
| 147 | `x` as the username and `$GIT_SECRET` as the password: |
| 148 | |
| 149 | ```sh |
| 150 | git remote add origin "$HOST/acme/web.git" |
| 151 | git -c credential.helper= push -u origin main |
| 152 | ``` |
| 153 | |
| 154 | Clone it back to prove the round trip: |
| 155 | |
| 156 | ```sh |
| 157 | git -c credential.helper= clone "$HOST/acme/web.git" verify |
| 158 | git -C verify fsck --strict |
| 159 | ``` |
| 160 | |
| 161 | ## Continue with the tutorial |
| 162 | |
| 163 | The tutorial introduces one behavior per part. Each part includes a deploy and |
| 164 | commands that verify what changed: |
| 165 | |
| 166 | 1. [Push your first repository](/git/tutorial/part-1) — deploy Git, push a commit, |
| 167 | and clone it back. |
| 168 | 2. [Control access](/git/tutorial/part-2) — require a shared credential and verify |
| 169 | anonymous requests fail. |
| 170 | 3. [Publish a repository](/git/tutorial/part-3) — allow anonymous clones while |
| 171 | keeping writes protected. |
| 172 | 4. [Give users their own credentials](/git/tutorial/part-4) — use accounts and |
| 173 | individual API keys. |
| 174 | 5. [Add your application's API](/git/tutorial/part-5) — serve `/me` beside Git |
| 175 | with the same authenticated user. |
| 176 | 6. [Protect a branch](/git/tutorial/part-6) — reject deletion of `main` with a |
| 177 | policy in your HTTP handler. |
| 178 | |
| 179 | [Building blocks](/git/blocks) is the reference for each line of |
| 180 | `GitLive`, and [Recipes](/git/recipes) covers S3 bytes, Lambda hashing, |
| 181 | and how the host scales. |