Skip to content

self_hosting: add the complete self-hosting guide - #23

Merged
max-tet merged 5 commits into
mainfrom
self-hosting-page
Nov 19, 2026
Merged

max-tet merged 5 commits into
mainfrom
self-hosting-page

Conversation

@ClaydeCode

@ClaydeCode ClaydeCode commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

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

  • New top-level nav section Self-Hosting with 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.
    • Prerequisites: Linux with Docker and the Compose plugin, ports 80/443/8883 and the portal network free (a dedicated host recommended), root, no tested RAM/disk minimum, *.localhost resolution, wildcard DNS.
    • Getting the files (curl from main), a local test, a server deployment, certificates (Azure DNS only today, freeshard#292).
    • Pairing further devices through Devices → Pair new device, with the API call as a fallback when no paired device is left.
    • Configuration table for the four .env variables of the compose in freeshard#317; rollout flags are not exposed, the compose turns them all on.
    • The owner's email address (recommendation: set it right after pairing, since the login provider passes it to apps), what still comes from Freeshard's infrastructure (moved from the README), known gaps with their issues, backups, updating, uninstalling.
  • agents.md: structure, nav and commit scopes updated for the new section.

Checks

mkdocs build --strict passes.

Merge order

Merge together with FreeshardBase/freeshard#317, and before FreeshardBase/landing-page#38, whose footer links this page.

🤖 Generated with Claude Code

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>
@ClaydeCode ClaydeCode changed the title self_hosting: add a prerequisites and known-gaps page self_hosting: add the complete self-hosting guide Nov 19, 2026
Comment thread docs/self_hosting/index.md Outdated

## 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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Multi Arch is on main, this line can go.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed.

Comment thread docs/self_hosting/index.md Outdated
## 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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mentioning the retired toll is not necessary.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed.

Comment thread docs/self_hosting/index.md Outdated

* **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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now only ports and network as the requirement; the dedicated host is a recommendation, with the reason under Known gaps.

Comment thread docs/self_hosting/index.md Outdated
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:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a fallback method. The real method is through the UI of a paired shard.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/self_hosting/index.md Outdated
| `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 |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will be false by default.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PRUNE_IMAGES is gone from the compose and the table; pruning stays off.

Comment thread docs/self_hosting/index.md Outdated
| `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 |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should not be a setting. Sundial is the only official UI now.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed from the table; the compose sets FREESHARD_SUNDIAL__ENABLED=true and no longer runs web-terminal.

Comment thread docs/self_hosting/index.md Outdated
Comment on lines +95 to +96
| `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 |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are feature flags and only configurable to enable gradual rollout across managed shards. Should not be an option for selfhosting.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correction after Max's follow-up: the compose now turns every rollout flag on (Sundial, OIDC, pause), fixed rather than configurable.

Comment thread docs/self_hosting/index.md Outdated
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That section needs a clear recommendation, not just information.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

ClaydeCode and others added 3 commits November 19, 2026 11:29
…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>
@max-tet
max-tet merged commit 24ff8e0 into main Nov 19, 2026
4 checks passed
@max-tet
max-tet deleted the self-hosting-page branch November 19, 2026 12:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs.freeshard.net has no install/self-hosting page

2 participants