tangled.org
Monorepo for Tangled
tangled.org
docs: tangled sites
Signed-off-by: Anirudh Oppiliappan <anirudh@tangled.org>
anirudh.fi
+106
-4
docs/DOCS.md
+106
-4
docs/DOCS.md
···
278
278
git push tangled main
279
279
```
280
280
281
+
# Hosting websites on Tangled
282
+
283
+
You can serve static websites directly from your git repositories on
284
+
Tangled. If you've used GitHub Pages or Codeberg Pages, this should feel
285
+
familiar.
286
+
287
+
## Overview
288
+
289
+
Every user gets a sites domain. If you signed up through Tangled's own
290
+
PDS (`tngl.sh`), your sites domain is automatically
291
+
`<your-handle>.tngl.sh` no setup needed. Otherwise, you can claim a
292
+
`<subdomain>.tngl.io` domain from your settings.
293
+
294
+
You can serve multiple sites per domain:
295
+
296
+
- One **index site** served at the root of your domain (e.g.
297
+
`alice.tngl.sh`)
298
+
- Any number of **sub-path sites** served under the repository name
299
+
(e.g. `alice.tngl.sh/my-project`)
300
+
301
+
## Claiming a domain
302
+
303
+
If you don't have a `tngl.sh` handle, you need to claim a domain before
304
+
publishing sites:
305
+
306
+
1. Go to **Settings → Sites**
307
+
2. Enter a subdomain (e.g. `alice` to claim `alice.tngl.io`)
308
+
3. Click **claim**
309
+
310
+
You can only hold one domain at a time. Releasing a domain puts it in a
311
+
30-day cooldown before anyone else can claim it.
312
+
313
+
## Configuring a site for a repository
314
+
315
+
1. Navigate to your repository
316
+
2. Go to **Settings → Sites**
317
+
3. Choose a **branch** to deploy from
318
+
4. Set the **deploy directory** — the path within the repository
319
+
containing your `index.html`. Use `/` for the root, or a subdirectory
320
+
like `/docs` or `/public`
321
+
5. Choose the **site type**:
322
+
- **Index site** — served at the root of your domain (e.g.
323
+
`alice.tngl.sh`)
324
+
- **Sub-path site** — served under the repository name (e.g.
325
+
`alice.tngl.sh/my-project`)
326
+
6. Click **save**
327
+
328
+
The site will be deployed automatically. You can see the status of your
329
+
previous deploys in the **Recent Deploys** section at the bottom of the
330
+
page.
331
+
332
+
Sites are redeployed automatically on every push to the configured
333
+
branch.
334
+
335
+
## Custom domains
336
+
337
+
Tangled currently doesn't support custom domains for sites. This will be
338
+
added in a future update.
339
+
340
+
## Deploy directory
341
+
342
+
The deploy directory is the path within your repository that Tangled
343
+
serves as the site root. It must contain an `index.html`.
344
+
345
+
| Deploy directory | Result |
346
+
|---|---|
347
+
| `/` | Serves the repository root |
348
+
| `/docs` | Serves the `docs/` subdirectory |
349
+
| `/public` | Serves the `public/` subdirectory |
350
+
351
+
Directories are served with automatic `index.html` resolution -- a
352
+
request to `/about` will serve `/about/index.html` if it exists.
353
+
354
+
## Site types
355
+
356
+
| Type | URL |
357
+
|---|---|
358
+
| Index site | `alice.tngl.sh` |
359
+
| Sub-path site | `alice.tngl.sh/my-project` |
360
+
361
+
Only one repository can be the index site for a given domain at a time.
362
+
If another repository already holds the index site, you will see a
363
+
notice in the settings and only the sub-path option will be available.
364
+
365
+
## Deploy triggers
366
+
367
+
A deployment is triggered automatically when:
368
+
369
+
- You push to the configured branch
370
+
- You change the site configuration (branch, deploy directory, or site
371
+
type)
372
+
373
+
## Disabling a site
374
+
375
+
To stop serving a site, go to **Settings → Sites** in your repository
376
+
and click **Disable**. This removes the site configuration and stops
377
+
serving the site. The deployed files are also deleted from storage.
378
+
379
+
Releasing your domain from **Settings → Sites** at the account level
380
+
will disable all sites associated with it and delete their files.
381
+
382
+
281
383
# Knot self-hosting guide
282
384
283
385
So you want to run your own knot server? Great! Here are a few prerequisites:
···
1236
1338
1237
1339
To set up a webhook for your repository:
1238
1340
1239
-
1. Navigate to your repository settings
1240
-
2. Click the "hooks" tab
1241
-
3. Click "add webhook"
1341
+
1. Navigate to your repository
1342
+
2. Go to **Settings → Hooks**
1343
+
3. Click **new webhook**
1242
1344
4. Configure your webhook:
1243
1345
- **Payload URL**: The endpoint that will receive the webhook POST requests
1244
-
- **Secret**: An optional secret key for verifying webhook authenticity (auto-generated if left blank)
1346
+
- **Secret**: An optional secret key for verifying webhook authenticity (leave blank to send unsigned webhooks)
1245
1347
- **Events**: Select which events trigger the webhook (currently only push events)
1246
1348
- **Active**: Toggle whether the webhook is enabled
1247
1349