The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 181 lines 6.15 KB
Raw
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.