Help
/
pages
Login
Radicle Pages

Publishing your Static Site on Radicle Pages

Radicle Pages is the static-site hosting service in Radicle Garden. It allows you to host your sites under https://<your-handle>.radicle.page, with support for custom domains coming soon. All you need is a Radicle repository, with a pages branch, seeded on your Radicle Garden account. Every push to that branch triggers redeploys your site.

Quick Start

If you have an active subscription, this is all you need:

  1. Seed a Radicle repository from your dashboard.

  2. Enable Pages from the settings.

  3. Push to the pages branch and watch your site go live on <your-handle>.radicle.page.

That’s it! A TLS certificate is issued automatically on the first visit and there is nothing else to configure. Storage space is already included in your Garden account.

For more details, check out the detailed setup guide below.

Setup Guide

Please follow the instructions below to have your static sites hosted on Radicle Pages.

1. Prepare your repository for Radicle Pages

To start, you need a public Radicle repository. Running rad init, inside any git repository, will guide you through the steps of creating that Radicle repository, but before you run that please read below to decide what your default branch should be called.

1.1. Choosing your default branch

If you will only work on a single git branch that contains your static site files (i.e. HTML, JS, CSS, media assets, etc.), we recommend you choose pages as the name of your default branch when running rad init. If this is your case, you can already skip ahead to Publish your Site on Radicle Pages.

If you are relying on a static site generator like Hugo or Jekyll, then chances are it makes more sense to pick whatever branch you work on (e.g. main, trunk, master, etc.) as the default branch for your Radicle repository when rad init asks you about that and set up an additional pages canonical branch (see below).

1.2 Setting up an additional pages branch

In Radicle, when you create a new git branch that others should converge on, you need to also capture how they’ll converge. This happens through Canonical Reference rules, which you encode in the Radicle repository itself. (For more details, you can check out this guide.)

To create your pages branch as a canonical reference, create the rule like so:

# First you create a proposal to change the project settings (a.k.a. "identity document"),
# adding a rule that states how `refs/heads/pages` is governed.
rad id update \
    --title "Configure `pages` canonical branch" \
    --payload xyz.radicle.crefs rules '{
        "refs/heads/pages":  { "allow": "delegates", "threshold": 1 },
    }'
# Then publish this proposal.
rad sync
# If you are the only delegate in this project, you will see this proposal has already
# been accepted (i.e. reached "quorum"). If you have more delegates on this project, then
# they will need to accept with `rad id accept <proposal_id>`.

If everything has gone well you will now be able to see:

❯ git ls-remote rad
fda215c2c4b1f428a7d0f0b09c8282d0784047c6        HEAD
fda215c2c4b1f428a7d0f0b09c8282d0784047c6        refs/heads/main
465203b78ab86b27a06cb795ffd4065a62eca38c        refs/heads/pages

2. Publish your Site on Radicle Pages

With your repository now fully set up with its pages branch:

  1. Log into radicle.garden

  2. Seed the new Radicle repository you created by clicking on "Add a repo"

  3. Paste the Radicle repository id (you can find it by running rad . in the folder on your filesystem) and click "Add"

  4. Wait for a few seconds (depending on the size of your repo and network congestion) for your Radicle node to perform the initial fetch of your repository from the network. (Only slow the first time)

  5. Find your project in the list, click the dropdown menu on the right (3 dots) and select "Settings"

  6. Scroll down to the Pages section. To enable this section, you also need to define a "Clone Alias":

    • if you want this site to be served at the site root (<your-handle>.radicle.page), select "pages" as the Clone Alias

    • if you select anything other than pages (e.g. some-slug) your site will be served at <your-handle>.radicle.page/some-slug. This allows you to host multiple static sites under the same account.

  7. Once you have saved the Clone Alias, the "Publish" button will be enabled, so you can deploy your site.

  8. From this point on, you just git push to the pages branch and watch your changes go live on your site. 🎉

Radicle Pages features

Radicle Pages is built on the excellent, Open Source, git-pages, so it supports all its neat features out of the box:

  • Site root: the repository root is served at /; index.html is the home page.

  • Custom 404: put a 404.html at the root; it’s served for missing paths.

  • Redirects: add a _redirects file at the root (Netlify-style rules). Malformed rules are ignored.

  • Custom headers: add a _headers file at the root (Netlify-style). Only headers allowlisted by this deployment are applied.

Limitations

  • The maximum site size is currently set: 128 MB.

  • No support for custom domains yet.

  • While git-pages has recently released its "Previews" feature, this is not yet supported in Radicle Pages.

Support

As usual, if you need assistance, please create a new topic on the Garden channel on Radicle Zulip.

Help