Repository navigation
self_hosting: add the complete self-hosting guide - #23
Conversation
docs.freeshard.net had no page for running a shard yourself, so the README was the only source and nothing stated the prerequisites (#13). The page lists them, the remaining dependency on Freeshard's infrastructure and the open shard_core issues, and links the README for the steps. Closes #13 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README now only links here (FreeshardBase/freeshard#317), so the page carries the full instructions: getting the files, a local test, a server deployment, certificates, a configuration table, the owner's email address, what still comes from Freeshard, backups, updating and uninstalling. Commands and variables match the compose file of that PR. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
|
||
| ## Prerequisites | ||
|
|
||
| * **A Linux machine with an x86-64 (amd64) CPU.** The Shard Core image is only built for amd64, so ARM boards such as a Raspberry Pi will not work. |
There was a problem hiding this comment.
Multi Arch is on main, this line can go.
| ## Prerequisites | ||
|
|
||
| * **A Linux machine with an x86-64 (amd64) CPU.** The Shard Core image is only built for amd64, so ARM boards such as a Raspberry Pi will not work. | ||
| * **Docker Engine with the Compose v2 plugin.** All commands below use `docker compose`. The retired v1 tool `docker-compose` is not supported. |
There was a problem hiding this comment.
Mentioning the retired toll is not necessary.
|
|
||
| * **A Linux machine with an x86-64 (amd64) CPU.** The Shard Core image is only built for amd64, so ARM boards such as a Raspberry Pi will not work. | ||
| * **Docker Engine with the Compose v2 plugin.** All commands below use `docker compose`. The retired v1 tool `docker-compose` is not supported. | ||
| * **A host to itself.** Ports 80, 443 and 8883 must be free, and there must be no Docker network called `portal`. Both are fixed in the compose file ([#196](https://github.com/FreeshardBase/freeshard/issues/196)). Shard Core also removes unused Docker images on the host once a day (see `PRUNE_IMAGES` under [Configuration](#configuration)). A dedicated machine or VM is the easiest setup. |
There was a problem hiding this comment.
Prune will be deactivated by default so the only thing really needed are ports and network. A ghost to itself is recommended but not strictly necessary.
There was a problem hiding this comment.
Now only ports and network as the requirement; the dedicated host is a recommendation, with the reason under Known gaps.
| It shows the Freeshard logo, the shard's address `http://<shard id>.localhost` and, as long as no device is paired, a pairing link that is valid for 10 minutes. | ||
| 4. Open the pairing link in your browser. If the code is not filled in, type it into the pairing field. | ||
|
|
||
| To pair another device later, get a fresh code from inside the shard's network: |
There was a problem hiding this comment.
That is a fallback method. The real method is through the UI of a paired shard.
There was a problem hiding this comment.
The UI route (Devices → Pair new device) is now the main instruction; the curl call stays as the fallback when no paired device is left.
| | `EMAIL` | | Contact address for Let's Encrypt | | ||
| | `DISABLE_SSL` | `false` | `true` only for a local test without certificates | | ||
| | `EMAIL_ENABLED` | `false` | Keep `false`, see [The owner's email address](#the-owners-email-address) | | ||
| | `PRUNE_IMAGES` | `true` | Once a day at 04:00, removes Docker images that no container uses and that are older than 24 hours. This applies to every image on the host, not only the shard's. Set it to `false` if the host runs other containers | |
There was a problem hiding this comment.
PRUNE_IMAGES is gone from the compose and the table; pruning stays off.
| | `DISABLE_SSL` | `false` | `true` only for a local test without certificates | | ||
| | `EMAIL_ENABLED` | `false` | Keep `false`, see [The owner's email address](#the-owners-email-address) | | ||
| | `PRUNE_IMAGES` | `true` | Once a day at 04:00, removes Docker images that no container uses and that are older than 24 hours. This applies to every image on the host, not only the shard's. Set it to `false` if the host runs other containers | | ||
| | `SUNDIAL_ENABLED` | `false` | `true` serves Sundial, the new web interface, at the shard's root instead of the current one | |
There was a problem hiding this comment.
This should not be a setting. Sundial is the only official UI now.
There was a problem hiding this comment.
Removed from the table; the compose sets FREESHARD_SUNDIAL__ENABLED=true and no longer runs web-terminal.
| | `OIDC_ENABLED` | `false` | `true` turns on the shard's built-in login provider for apps | | ||
| | `PAUSE_ENABLED` | `false` | `true` pauses idle apps first and stops them only later or when memory gets tight, so they come back faster | |
There was a problem hiding this comment.
Those are feature flags and only configurable to enable gradual rollout across managed shards. Should not be an option for selfhosting.
There was a problem hiding this comment.
Removed; the compose no longer sets them, so the core defaults (off) apply. EMAIL_ENABLED is gone as well: mail needs the controller, so the compose fixes it to false.
There was a problem hiding this comment.
Correction after Max's follow-up: the compose now turns every rollout flag on (Sundial, OIDC, pause), fixed rather than configurable.
| With `true`, setting an address fails with HTTP 502 and the address stays unconfirmed. | ||
|
|
||
| The confirmed address is what the built-in login provider passes to apps. | ||
| Without one, apps you log into through it create fresh accounts instead of linking to an existing one by address. |
There was a problem hiding this comment.
That section needs a clear recommendation, not just information.
There was a problem hiding this comment.
Now opens with the recommendation: leave it empty, since nothing on a self-hosted shard uses it yet (no mail, no app reads it, login provider off).
There was a problem hiding this comment.
Changed with the flags on: the recommendation is now to set the address right after pairing, before logging into any app, because the login provider passes it to apps.
…mend no owner email Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s on Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Closes #13.
docs.freeshard.net had no page about running a shard yourself; the README was the only guide and had gone stale.
What changes
self_hosting/index.md(URL/self_hosting/), the complete guide. The README's hosting section is replaced by a link to it in Match the self-hosting compose to hosted shards and move the guide to the docs freeshard#317, so the two land together.portalnetwork free (a dedicated host recommended), root, no tested RAM/disk minimum,*.localhostresolution, wildcard DNS.curlfrommain), a local test, a server deployment, certificates (Azure DNS only today, freeshard#292)..envvariables of the compose in freeshard#317; rollout flags are not exposed, the compose turns them all on.agents.md: structure, nav and commit scopes updated for the new section.Checks
mkdocs build --strictpasses.Merge order
Merge together with FreeshardBase/freeshard#317, and before FreeshardBase/landing-page#38, whose footer links this page.
🤖 Generated with Claude Code