@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 262 lines 7.52 KB
Raw
1 ---
2 title: "Part 1: Push your first repository"
3 description: Deploy a Git host, push a commit, and clone it back. Add storage and hashing one layer at a time.
4 ---
5
6 import { Code, Tabs, TabItem } from "@astrojs/starlight/components";
7 import PackageManagers from "../../../../components/PackageManagers.astro";
8
9 Start with a Git remote you can push to. This part deploys a Worker backed by
10 Durable Objects and R2, then sends a real commit through it and clones it back.
11
12 :::caution
13 This first deployment is open: anyone who knows its URL can create repositories,
14 read them, and write to them. Use a disposable repository. [Part 2](/git/tutorial/part-2)
15 adds access control before you use the host for private work.
16 :::
17
18 ## Create the project
19
20 You need Bun or Node.js 22+, Git, and a Cloudflare account with Workers, Durable Objects, and R2.
21 Complete [Cloudflare setup](/cloudflare/setup) to connect your account.
22
23 <Tabs syncKey="pkgManager">
24 <TabItem label="pnpm" icon="pnpm">
25 <Code code={`mkdir git-tutorial
26 cd git-tutorial
27 pnpm init
28 pnpm add alchemy @alchemy.run/cloudflare @alchemy.run/git effect
29 mkdir src`} lang="sh" />
30 </TabItem>
31 <TabItem label="bun" icon="bun">
32 <Code code={`mkdir git-tutorial
33 cd git-tutorial
34 bun init -y
35 bun add alchemy @alchemy.run/cloudflare @alchemy.run/git effect
36 mkdir src`} lang="sh" />
37 </TabItem>
38 <TabItem label="npm" icon="npm">
39 <Code code={`mkdir git-tutorial
40 cd git-tutorial
41 npm init -y
42 npm install alchemy @alchemy.run/cloudflare @alchemy.run/git effect
43 mkdir src`} lang="sh" />
44 </TabItem>
45 <TabItem label="yarn" icon="seti:yarn">
46 <Code code={`mkdir git-tutorial
47 cd git-tutorial
48 yarn init -y
49 yarn add alchemy @alchemy.run/cloudflare @alchemy.run/git effect
50 mkdir src`} lang="sh" />
51 </TabItem>
52 </Tabs>
53
54 Run the remaining commands from this project directory. Keep the same directory,
55 stack name, and deployment stage throughout the tutorial so each deploy updates
56 this host.
57
58 ## Add the Git routes
59
60 Create `src/git.ts`:
61
62 ```typescript
63 // src/git.ts
64 import * as Git from "@alchemy.run/git";
65 import * as Layer from "effect/Layer";
66
67 export const GitLive = Git.ApiLive.pipe(
68 Layer.provide(Git.ApiHandlersLive),
69 );
70 ```
71
72 `Git.ApiLive` registers the Git HTTP endpoints, including the protocol used by
73 `git push` and `git clone`. `Git.ApiHandlersLive` implements those endpoints.
74 Its remaining dependencies describe where repositories live and how incoming
75 objects are checked. Supply each one below before deploying.
76
77 ## Store repository data
78
79 ```diff lang="typescript"
80 // src/git.ts
81 export const GitLive = Git.ApiLive.pipe(
82 Layer.provide(Git.ApiHandlersLive),
83 + Layer.provide(Git.ReposDurableObject),
84 );
85 ```
86
87 `Git.ReposDurableObject` gives each repository a Durable Object. It stores the
88 repository's refs and object metadata and coordinates writes to that repository.
89
90 ## Look up repositories by name
91
92 ```diff lang="typescript"
93 // src/git.ts
94 Layer.provide(Git.ReposDurableObject),
95 + Layer.provide(Git.RegistryDurableObject),
96 );
97 ```
98
99 The registry maps an `owner/name`, such as `acme/web`, to its repository. This
100 lets an incoming request find the right Durable Object.
101
102 ## Verify incoming Git objects
103
104 ```diff lang="typescript"
105 // src/git.ts
106 Layer.provide(Git.RegistryDurableObject),
107 + Layer.provide(Git.HasherInline),
108 );
109 ```
110
111 Git objects are identified by hashes of their contents. `Git.HasherInline`
112 verifies incoming objects in the Worker during a push.
113
114 ## Store packs and large objects
115
116 ```diff lang="typescript"
117 // src/git.ts
118 +import * as Cloudflare from "@alchemy.run/cloudflare";
119 import * as Git from "@alchemy.run/git";
120 import * as Layer from "effect/Layer";
121
122 +const GitObjects = Cloudflare.R2.Bucket("GitObjects", { forceDestroy: true });
123 +
124 export const GitLive = Git.ApiLive.pipe(
125 ```
126
127 This bucket holds packs, clone bundles, and large objects. `forceDestroy: true`
128 lets you remove the tutorial stack even when the bucket contains data; destroying
129 this stack also deletes those objects.
130
131 Connect the bucket to Git:
132
133 ```diff lang="typescript"
134 // src/git.ts
135 Layer.provide(Git.HasherInline),
136 + Layer.provide(Git.BlobStoreR2(GitObjects)),
137 );
138 ```
139
140 The R2 layer supplies the blob-storage operations used by the Worker and the
141 repository Durable Objects.
142
143 ## Serve Git from a Worker
144
145 Create `src/host.ts`:
146
147 ```typescript
148 // src/host.ts
149 import * as Cloudflare from "@alchemy.run/cloudflare";
150 import * as Git from "@alchemy.run/git";
151 import * as Http from "alchemy/Http";
152 import * as Effect from "effect/Effect";
153 import * as Layer from "effect/Layer";
154 import * as HttpRouter from "effect/http/HttpRouter";
155 import { GitLive } from "./git.ts";
156
157 export default class GitHost extends Cloudflare.Worker<GitHost>()(
158 "GitHost",
159 { main: import.meta.url, ...Git.GIT_WORKER_OPTIONS },
160 Effect.gen(function* () {
161 const fetch = yield* HttpRouter.toHttpEffect(
162 GitLive.pipe(Layer.provide(Http.Platform)),
163 );
164 return { fetch };
165 }).pipe(Effect.provide(Cloudflare.R2.ReadWriteBucketBinding)),
166 ) {}
167 ```
168
169 `HttpRouter.toHttpEffect` turns the route layer into the Worker's `fetch` handler.
170 `Http.Platform` provides its HTTP platform dependencies. `GIT_WORKER_OPTIONS`
171 sets the Worker compatibility flags and CPU limit used by Git.
172 `Cloudflare.R2.ReadWriteBucketBinding` binds the bucket to the Worker so
173 `BlobStoreR2` can read and write it.
174
175 ## Declare the stack
176
177 Create `alchemy.run.ts`:
178
179 ```typescript
180 // alchemy.run.ts
181 import * as Alchemy from "alchemy";
182 import * as Cloudflare from "@alchemy.run/cloudflare";
183 import * as Effect from "effect/Effect";
184 import GitHost from "./src/host.ts";
185
186 export default Alchemy.Stack(
187 "GitTutorial",
188 { providers: Cloudflare.providers(), state: Cloudflare.state() },
189 Effect.gen(function* () {
190 const host = yield* GitHost;
191 return { url: host.url.as<string>() };
192 }),
193 );
194 ```
195
196 Yielding the Worker includes its bucket and Durable Object bindings in the
197 stack. The output gives you the URL clients will use.
198
199 ## Deploy
200
201 <PackageManagers run="alchemy deploy" />
202
203 Copy the printed URL, including `https://`, without a trailing slash:
204
205 ```sh
206 export HOST="https://your-worker.workers.dev"
207 ```
208
209 Verify that the Git API is reachable:
210
211 ```sh
212 curl --fail-with-body "$HOST/api/v1/repos"
213 ```
214
215 It returns a JSON repository list. On a new host the list is empty. A new
216 `workers.dev` deployment can briefly return a Cloudflare 404 while it propagates;
217 repeat this read check until the API responds before creating the repository.
218 Updates in later parts can also briefly serve the previous version.
219
220 ## Create a repository
221
222 ```sh
223 curl --fail-with-body -X POST "$HOST/api/v1/repos" \
224 -H "Content-Type: application/json" \
225 -d '{"owner":"acme","name":"web"}'
226 ```
227
228 The repository is named `acme/web`. At this stage `acme` is just a namespace;
229 there are no user accounts. Creating a repository reserves that name before you
230 push any commits.
231
232 ## Push a commit
233
234 ```sh
235 git init -b main work
236 git -C work config user.name "Tutorial"
237 git -C work config user.email "tutorial@example.com"
238 printf '# My repository\n' > work/README.md
239 git -C work add README.md
240 git -C work commit -m "First commit"
241 git -C work remote add origin "$HOST/acme/web.git"
242 git -C work push -u origin main
243 ```
244
245 The push uploads the commit and its objects, then creates `main` on your host.
246
247 ## Clone it back
248
249 ```sh
250 git clone "$HOST/acme/web.git" verify
251 git -C verify fsck --strict
252 git -C work rev-parse HEAD
253 git -C verify rev-parse HEAD
254 ```
255
256 The two commit IDs should match, and `fsck` should report no corrupt or missing
257 objects. You now have a working Git remote.
258
259 Continue to [Part 2: Control access](/git/tutorial/part-2). If you stop here,
260 remove the open learning deployment:
261
262 <PackageManagers run="alchemy destroy" />