From effb6ad62f075e8b6aca2a5ca1c4bd9e478de911 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Tue, 17 Nov 2026 15:10:57 +0000 Subject: [PATCH 1/5] self_hosting: add a prerequisites and known-gaps page 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 --- agents.md | 5 +-- docs/self_hosting/index.md | 72 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 ++ 3 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/self_hosting/index.md diff --git a/agents.md b/agents.md index d4ef34b..b737372 100644 --- a/agents.md +++ b/agents.md @@ -26,6 +26,7 @@ uv run mkdocs build # Generate static site to public/ docs/ overview/ Product overview and concepts concepts/ Single-user isolation, devices, apps + self_hosting/ Running a shard on your own machine (prerequisites, known gaps) developer_docs/ Developer documentation for app creators includes/ Reusable markdown snippets (template vars, portal name info) img/ Developer docs images @@ -39,7 +40,7 @@ mkdocs.yml Site config, navigation, theme, plugins ## Conventions ### Navigation -Navigation is explicitly defined in `mkdocs.yml` under the `nav` key. Three top-level sections: Overview, Developer Docs, User Guides. Adding a new page requires adding it to `nav`. +Navigation is explicitly defined in `mkdocs.yml` under the `nav` key. Four top-level sections: Overview, Developer Docs, Self-Hosting, User Guides. Adding a new page requires adding it to `nav`. ### Retired Blog The blog no longer lives here. It moved to `freeshard.net//blog/`, as an Astro content collection in the `landing-page` repo — write new posts there, not here. @@ -67,6 +68,6 @@ Built and deployed via GitHub Pages (`.github/workflows/ci.yml`). Every push bui [Scoped Commits](https://scopedcommits.com/): `: `. The scope is the area of the tree the change touches, never a change type — write `user_guides: document the backup restore flow`, not `fix(user_guides): ...`. Body and trailers are optional; a change's reasoning belongs in the body, not in a code comment. -Scopes for this repo: `blog` `developer_docs` `user_guides` `overview` `theme` `ci` `meta` +Scopes for this repo: `blog` `developer_docs` `self_hosting` `user_guides` `overview` `theme` `ci` `meta` `meta` covers repo-level files (agents.md, README, justfile). For a change spanning several scopes, use a broader one, list two comma-separated, or use `treewide`. Merges and reverts keep their own format. Don't generate a changelog from the commit log — release notes come from merged PRs. diff --git a/docs/self_hosting/index.md b/docs/self_hosting/index.md new file mode 100644 index 0000000..a13ebdd --- /dev/null +++ b/docs/self_hosting/index.md @@ -0,0 +1,72 @@ +# Self-Hosting + +Freeshard's software, Shard Core, can run on a machine of your own instead of a hosted shard. +Its source code is public under the [Functional Source License (FSL-1.1-ALv2)](https://github.com/FreeshardBase/freeshard/blob/main/LICENSE.md), which permits self-hosting. + +The step-by-step instructions live in the repository README, for both a [local test and a full server deployment](https://github.com/FreeshardBase/freeshard#hosting). +This page covers what you need before you start and what does not work yet, so you can decide before you spend time on it. + +!!! warning "Early stage" + A self-hosted shard runs, but the setup is not polished yet. + Every known gap is listed below with the issue that tracks it. + +## 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.** The command is `docker compose`; the README still says `docker-compose`, which is the retired v1 tool ([#134](https://github.com/FreeshardBase/freeshard/issues/134)). +* **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)). A dedicated machine or VM is the easiest setup. +* **Root or `sudo`.** The containers write the shard's data as root. +* **Memory and disk.** There is no tested minimum yet. For comparison, the smallest hosted shard has 1 vCPU and 2 GB of RAM. Apps are downloaded when they are first opened, and some are large: the Immich images alone are about 3.5 GB. +* **For a server on the internet: a domain with wildcard DNS.** Every app gets its own subdomain, so `*.` must point at the server, and the certificate has to be a wildcard certificate obtained through a DNS challenge. See [Certificates](#certificates) below before you rent a server for this. +* **For a local test: `*.localhost` resolution.** The shard is reached at `http://.localhost`. systemd-resolved resolves such names; plain glibc without it and Windows do not. + +All files (`docker-compose.yml`, `.env`) go into one directory, and the commands are run from there. +Both files are in the root of the [repository](https://github.com/FreeshardBase/freeshard); the env file is shipped as `.env.template`. +Set `FREESHARD_DIR` to an absolute path of your choice; the template's `/home/user/.freeshard` is only an example. + +## What a self-hosted shard still gets from Freeshard + +A self-hosted shard is not self-contained. +The app catalogue, the app packages and some app container images are served by infrastructure Freeshard operates. +The README explains [where the apps come from](https://github.com/FreeshardBase/freeshard#where-the-apps-come-from) and what you would have to replace to avoid that dependency ([#195](https://github.com/FreeshardBase/freeshard/issues/195)). + +The shard also still contacts Freeshard's management service, for example at startup and for the nightly backup. Those requests fail for a self-hosted shard, which has no account there ([#286](https://github.com/FreeshardBase/freeshard/issues/286)). + +## Known gaps + +### Certificates + +Today the shipped setup can only obtain a Let's Encrypt certificate through Azure DNS. +With any other DNS provider, Traefik serves its own self-signed certificate ([#292](https://github.com/FreeshardBase/freeshard/issues/292)). +A local test with `DISABLE_SSL=true` is not affected. + +### Email + +A self-hosted shard cannot send mail, so mail confirmation has to be switched off, or setting the owner's email address fails with HTTP 502. +The README says to do this in `local_config.toml`, but the container never reads that file ([#300](https://github.com/FreeshardBase/freeshard/issues/300)). +Until that is fixed, add this line to the `environment` list of the `shard_core` service in `docker-compose.yml`: + +```yaml + - FREESHARD_EMAIL__ENABLED=false +``` + +### Backups + +The nightly backup depends on Freeshard's management service and fails on a self-hosted shard, although the interface says a backup runs every night ([#286](https://github.com/FreeshardBase/freeshard/issues/286)). +Back up `FREESHARD_DIR` yourself. +The README section [Backup and Restore](https://github.com/FreeshardBase/freeshard#backup-and-restore) describes what it contains. + +### Isolation + +Shard Core and Traefik have access to the Docker socket, which amounts to root access on the host. +Run a shard on a machine or VM that does nothing else you care about ([#198](https://github.com/FreeshardBase/freeshard/issues/198)). + +## Uninstalling + +`docker compose down` stops and removes the containers. +It does not remove any data, not even with `-v`: everything lives in `FREESHARD_DIR`, including the shard's private key, the database and all user data. +To remove the shard completely, delete that directory, which needs `sudo` because the files belong to root. + +## Questions + +If something on this page is wrong or out of date, or you get stuck, open an issue on [GitHub](https://github.com/FreeshardBase/freeshard/issues) or write to [contact@freeshard.net](mailto:contact@freeshard.net). diff --git a/mkdocs.yml b/mkdocs.yml index 61ad00a..308ebf1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,6 +52,8 @@ nav: - 'developer_docs/revenue_share.md' - 'developer_docs/existing_apps.md' # - 'developer_docs/app_template.md' + - Self-Hosting: + - 'self_hosting/index.md' - User Guides: - 'user_guides/password_management.md' - 'user_guides/smart_home.md' From a34444cfe3bca1fda1218fa66e7147ad62212405 Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Thu, 19 Nov 2026 08:22:05 +0000 Subject: [PATCH 2/5] self_hosting: make the page the complete install guide 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 --- docs/self_hosting/index.md | 158 +++++++++++++++++++++++++++++-------- 1 file changed, 124 insertions(+), 34 deletions(-) diff --git a/docs/self_hosting/index.md b/docs/self_hosting/index.md index a13ebdd..0539bd0 100644 --- a/docs/self_hosting/index.md +++ b/docs/self_hosting/index.md @@ -3,69 +3,159 @@ Freeshard's software, Shard Core, can run on a machine of your own instead of a hosted shard. Its source code is public under the [Functional Source License (FSL-1.1-ALv2)](https://github.com/FreeshardBase/freeshard/blob/main/LICENSE.md), which permits self-hosting. -The step-by-step instructions live in the repository README, for both a [local test and a full server deployment](https://github.com/FreeshardBase/freeshard#hosting). -This page covers what you need before you start and what does not work yet, so you can decide before you spend time on it. +This page is the complete guide: what you need, how to try it locally, how to run it on a server, and what does not work yet. !!! warning "Early stage" A self-hosted shard runs, but the setup is not polished yet. - Every known gap is listed below with the issue that tracks it. + Every known gap is listed under [Known gaps](#known-gaps), with the issue that tracks it. ## 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.** The command is `docker compose`; the README still says `docker-compose`, which is the retired v1 tool ([#134](https://github.com/FreeshardBase/freeshard/issues/134)). -* **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)). A dedicated machine or VM is the easiest setup. +* **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. * **Root or `sudo`.** The containers write the shard's data as root. * **Memory and disk.** There is no tested minimum yet. For comparison, the smallest hosted shard has 1 vCPU and 2 GB of RAM. Apps are downloaded when they are first opened, and some are large: the Immich images alone are about 3.5 GB. -* **For a server on the internet: a domain with wildcard DNS.** Every app gets its own subdomain, so `*.` must point at the server, and the certificate has to be a wildcard certificate obtained through a DNS challenge. See [Certificates](#certificates) below before you rent a server for this. * **For a local test: `*.localhost` resolution.** The shard is reached at `http://.localhost`. systemd-resolved resolves such names; plain glibc without it and Windows do not. +* **For a server on the internet: a domain with wildcard DNS**, and for now a DNS zone hosted in Azure DNS. See [Certificates](#certificates) before you rent a server for this. -All files (`docker-compose.yml`, `.env`) go into one directory, and the commands are run from there. -Both files are in the root of the [repository](https://github.com/FreeshardBase/freeshard); the env file is shipped as `.env.template`. -Set `FREESHARD_DIR` to an absolute path of your choice; the template's `/home/user/.freeshard` is only an example. +## Get the files -## What a self-hosted shard still gets from Freeshard +A shard needs two files from the [repository](https://github.com/FreeshardBase/freeshard), in one directory of your choice. +Run every command on this page from that directory. -A self-hosted shard is not self-contained. -The app catalogue, the app packages and some app container images are served by infrastructure Freeshard operates. -The README explains [where the apps come from](https://github.com/FreeshardBase/freeshard#where-the-apps-come-from) and what you would have to replace to avoid that dependency ([#195](https://github.com/FreeshardBase/freeshard/issues/195)). +```shell +mkdir freeshard && cd freeshard +curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/FreeshardBase/freeshard/main/docker-compose.yml +curl -fsSL -o .env https://raw.githubusercontent.com/FreeshardBase/freeshard/main/.env.template +``` -The shard also still contacts Freeshard's management service, for example at startup and for the nightly backup. Those requests fail for a self-hosted shard, which has no account there ([#286](https://github.com/FreeshardBase/freeshard/issues/286)). +The compose file pins the same versions of Shard Core, Traefik, Postgres and the two web interfaces that hosted shards run. + +## Try it locally + +1. Edit `.env`: + * `FREESHARD_DIR`: an absolute path where all shard data will be stored. It is created on first start and owned by root. + * `DNS_ZONE`: leave it at `localhost`. + * `EMAIL`: can stay as it is, no certificates are requested. + * `DISABLE_SSL`: set it to `true`. +2. Start the shard: + ```shell + docker compose up -d + ``` +3. Read the welcome message: + ```shell + docker compose logs shard_core + ``` + It shows the Freeshard logo, the shard's address `http://.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: + +```shell +docker run --rm --network portal curlimages/curl -s "http://shard_core/protected/terminals/pairing-code" +``` -## Known gaps +Then open `http://.localhost/#/pair` on the new device and enter the code. + +## Run it on a server + +1. Use a server that is reachable from the internet, with a domain whose DNS you control. +2. Point the domain and every subdomain at the server. Each app gets its own subdomain under the shard's domain, so you need a wildcard record, for example `*.example.org`. The shard's own address is `.example.org`, which the wildcard covers. +3. [Get the files](#get-the-files) onto the server and edit `.env`: + * `FREESHARD_DIR`: an absolute path for all shard data. + * `DNS_ZONE`: your domain, for example `example.org`. + * `EMAIL`: your address, which Let's Encrypt uses for certificate notices. + * `DISABLE_SSL`: `false`. Never set it to `true` on a server reachable from the internet. +4. Set up certificates as described under [Certificates](#certificates). +5. Start the shard with `docker compose up -d`, then read the welcome message and pair your first device as in the local test. The address now starts with `https://`. ### Certificates -Today the shipped setup can only obtain a Let's Encrypt certificate through Azure DNS. -With any other DNS provider, Traefik serves its own self-signed certificate ([#292](https://github.com/FreeshardBase/freeshard/issues/292)). -A local test with `DISABLE_SSL=true` is not affected. +Every app lives on its own subdomain, so the shard needs a wildcard certificate, and Let's Encrypt issues those only through a DNS challenge. +Traefik answers that challenge by creating a DNS record through your DNS provider's API. -### Email +Today Shard Core configures Traefik for Azure DNS only, and the provider cannot be changed without rebuilding the image ([#292](https://github.com/FreeshardBase/freeshard/issues/292)). +If your zone is in Azure DNS, uncomment the `AZURE_*` variables and `LEGO_AZURE_BYPASS_DEPRECATION` of the `traefik` service in `docker-compose.yml` and fill them in with a service principal that may edit the zone ([Traefik's provider list](https://doc.traefik.io/traefik/v2.11/https/acme/#providers) names the variables). +With any other DNS provider, Traefik falls back to its own self-signed certificate, which browsers reject. -A self-hosted shard cannot send mail, so mail confirmation has to be switched off, or setting the owner's email address fails with HTTP 502. -The README says to do this in `local_config.toml`, but the container never reads that file ([#300](https://github.com/FreeshardBase/freeshard/issues/300)). -Until that is fixed, add this line to the `environment` list of the `shard_core` service in `docker-compose.yml`: +## Configuration -```yaml - - FREESHARD_EMAIL__ENABLED=false -``` +All settings live in `.env`. The first three are required; the rest are optional and fall back to the defaults shown. + +| Variable | Default | Meaning | +|---|---|---| +| `FREESHARD_DIR` | | Absolute path for all shard data | +| `DNS_ZONE` | | Domain the shard lives under; `localhost` for a local test | +| `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 | +| `SUNDIAL_ENABLED` | `false` | `true` serves Sundial, the new web interface, at the shard's root instead of the current one | +| `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 | + +After changing `.env`, run `docker compose up -d` again. + +### The owner's email address + +On a hosted shard, a new owner address only counts once its owner has opened a confirmation link mailed to it. +A self-hosted shard cannot send mail, so with `EMAIL_ENABLED=false` the address is taken as given, without a confirmation mail. +That is acceptable because you control the machine. +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. + +## What a self-hosted shard still gets from Freeshard + +A self-hosted shard is not self-contained ([#195](https://github.com/FreeshardBase/freeshard/issues/195)). Both halves of the app catalogue come from infrastructure Freeshard operates: + +* the catalogue and the app packages come from an Azure storage container (`apps.app_store` in [`config.toml`](https://github.com/FreeshardBase/freeshard/blob/main/config.toml)), and +* the container images of apps that do not use a public upstream image come from Freeshard's registry, `portalapps.azurecr.io`. + +Shard Core logs in to that registry with credentials that are committed to `config.toml` on purpose. +They belong to a service principal whose only permission anywhere is reading that one registry: it can pull images and read registry metadata, nothing else. +Every shard needs it to install apps. +If you would rather not depend on Freeshard's infrastructure, these two are what you would have to replace. + +The shard also still contacts Freeshard's management service, for example at startup and for the nightly backup. +Those requests fail for a self-hosted shard, which has no account there ([#286](https://github.com/FreeshardBase/freeshard/issues/286)). + +## Known gaps -### Backups +* **Certificates only through Azure DNS** ([#292](https://github.com/FreeshardBase/freeshard/issues/292)), see [Certificates](#certificates). +* **No automatic backup.** The nightly backup depends on Freeshard's management service and fails on a self-hosted shard, although the interface says a backup runs every night ([#286](https://github.com/FreeshardBase/freeshard/issues/286)). See [Backups](#backups). +* **The shard assumes it owns the host:** fixed ports, a fixed network name, and Traefik also picks up other containers on the host ([#196](https://github.com/FreeshardBase/freeshard/issues/196)). +* **Isolation.** Shard Core and Traefik have access to the Docker socket, which amounts to root access on the host. Run a shard on a machine or VM that does nothing else you care about ([#198](https://github.com/FreeshardBase/freeshard/issues/198)). -The nightly backup depends on Freeshard's management service and fails on a self-hosted shard, although the interface says a backup runs every night ([#286](https://github.com/FreeshardBase/freeshard/issues/286)). -Back up `FREESHARD_DIR` yourself. -The README section [Backup and Restore](https://github.com/FreeshardBase/freeshard#backup-and-restore) describes what it contains. +## Backups -### Isolation +Everything a shard has is in `FREESHARD_DIR`: its identity and private key, the database, the installed apps and all user data. +Back up that directory, ideally with the shard stopped (`docker compose stop`) so the database is consistent. +The repository README describes [how hosted shards back up and restore](https://github.com/FreeshardBase/freeshard#backup-and-restore). -Shard Core and Traefik have access to the Docker socket, which amounts to root access on the host. -Run a shard on a machine or VM that does nothing else you care about ([#198](https://github.com/FreeshardBase/freeshard/issues/198)). +## Updating + +Download the current `docker-compose.yml` again (see [Get the files](#get-the-files)), keep your `.env`, and run: + +```shell +docker compose up -d +``` + +Docker pulls the new images and recreates the containers. Database migrations run when Shard Core starts. +If you changed `docker-compose.yml` yourself, for example for certificates, carry those changes over. ## Uninstalling `docker compose down` stops and removes the containers. -It does not remove any data, not even with `-v`: everything lives in `FREESHARD_DIR`, including the shard's private key, the database and all user data. -To remove the shard completely, delete that directory, which needs `sudo` because the files belong to root. +It does not remove any data, not even with `-v`: everything lives in `FREESHARD_DIR`, including the shard's private key. +To remove the shard completely, delete that directory, which needs `sudo` because the files belong to root: + +```shell +docker compose down +sudo rm -rf +``` ## Questions From be4a0aed7dfd2de2b50ec828d59d4ea4dad3a42d Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Thu, 19 Nov 2026 11:29:04 +0000 Subject: [PATCH 3/5] self_hosting: address review, drop rollout flags and arch note, recommend no owner email Co-Authored-By: Claude Opus 5.5 --- docs/self_hosting/index.md | 43 +++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/docs/self_hosting/index.md b/docs/self_hosting/index.md index 0539bd0..75263b0 100644 --- a/docs/self_hosting/index.md +++ b/docs/self_hosting/index.md @@ -11,9 +11,8 @@ This page is the complete guide: what you need, how to try it locally, how to ru ## 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. -* **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. +* **A Linux machine** with Docker Engine and the Compose plugin (`docker compose`). +* **Free ports and network name.** 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)). A dedicated machine or VM is recommended, see [Known gaps](#known-gaps). * **Root or `sudo`.** The containers write the shard's data as root. * **Memory and disk.** There is no tested minimum yet. For comparison, the smallest hosted shard has 1 vCPU and 2 GB of RAM. Apps are downloaded when they are first opened, and some are large: the Immich images alone are about 3.5 GB. * **For a local test: `*.localhost` resolution.** The shard is reached at `http://.localhost`. systemd-resolved resolves such names; plain glibc without it and Windows do not. @@ -30,7 +29,7 @@ curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/FreeshardBase curl -fsSL -o .env https://raw.githubusercontent.com/FreeshardBase/freeshard/main/.env.template ``` -The compose file pins the same versions of Shard Core, Traefik, Postgres and the two web interfaces that hosted shards run. +The compose file pins the same versions of Shard Core, Traefik, Postgres and the Sundial web interface that hosted shards run. ## Try it locally @@ -50,7 +49,10 @@ The compose file pins the same versions of Shard Core, Traefik, Postgres and the It shows the Freeshard logo, the shard's address `http://.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: +To pair another device, open **Devices** on a device that is already paired and choose **Pair new device**. +It shows a code and a QR code for the new device. + +If no paired device is left, get a fresh code from inside the shard's network instead: ```shell docker run --rm --network portal curlimages/curl -s "http://shard_core/protected/terminals/pairing-code" @@ -81,31 +83,24 @@ With any other DNS provider, Traefik falls back to its own self-signed certifica ## Configuration -All settings live in `.env`. The first three are required; the rest are optional and fall back to the defaults shown. +All settings live in `.env`, and all four are required. -| Variable | Default | Meaning | -|---|---|---| -| `FREESHARD_DIR` | | Absolute path for all shard data | -| `DNS_ZONE` | | Domain the shard lives under; `localhost` for a local test | -| `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 | -| `SUNDIAL_ENABLED` | `false` | `true` serves Sundial, the new web interface, at the shard's root instead of the current one | -| `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 | +| Variable | Meaning | +|---|---| +| `FREESHARD_DIR` | Absolute path for all shard data | +| `DNS_ZONE` | Domain the shard lives under; `localhost` for a local test | +| `EMAIL` | Contact address for Let's Encrypt | +| `DISABLE_SSL` | `true` only for a local test without certificates, otherwise `false` | After changing `.env`, run `docker compose up -d` again. ### The owner's email address -On a hosted shard, a new owner address only counts once its owner has opened a confirmation link mailed to it. -A self-hosted shard cannot send mail, so with `EMAIL_ENABLED=false` the address is taken as given, without a confirmation mail. -That is acceptable because you control the machine. -With `true`, setting an address fails with HTTP 502 and the address stays unconfirmed. +Leave the owner's email address under **Settings** empty. +Nothing on a self-hosted shard uses it yet: the shard cannot send mail, no app reads the address, and the login provider that passes it to apps is not enabled for self-hosted shards. +The hint on the Settings page that storage warnings and billing messages go to this address applies to hosted shards only. -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. +If you set one anyway, it counts as soon as you save it, because there is no confirmation mail. ## What a self-hosted shard still gets from Freeshard @@ -126,7 +121,7 @@ Those requests fail for a self-hosted shard, which has no account there ([#286]( * **Certificates only through Azure DNS** ([#292](https://github.com/FreeshardBase/freeshard/issues/292)), see [Certificates](#certificates). * **No automatic backup.** The nightly backup depends on Freeshard's management service and fails on a self-hosted shard, although the interface says a backup runs every night ([#286](https://github.com/FreeshardBase/freeshard/issues/286)). See [Backups](#backups). -* **The shard assumes it owns the host:** fixed ports, a fixed network name, and Traefik also picks up other containers on the host ([#196](https://github.com/FreeshardBase/freeshard/issues/196)). +* **The shard assumes it owns the host:** fixed ports, a fixed network name, and Traefik also picks up other containers on the host ([#196](https://github.com/FreeshardBase/freeshard/issues/196)). It works next to other services, but a dedicated machine or VM avoids these clashes. * **Isolation.** Shard Core and Traefik have access to the Docker socket, which amounts to root access on the host. Run a shard on a machine or VM that does nothing else you care about ([#198](https://github.com/FreeshardBase/freeshard/issues/198)). ## Backups From 1ac3f30eb6bdbbaa7b02948e078a31f183a3240f Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Thu, 19 Nov 2026 11:58:58 +0000 Subject: [PATCH 4/5] self_hosting: recommend setting the owner email, the login provider is on Co-Authored-By: Claude Opus 5.5 --- docs/self_hosting/index.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/self_hosting/index.md b/docs/self_hosting/index.md index 75263b0..ac29a22 100644 --- a/docs/self_hosting/index.md +++ b/docs/self_hosting/index.md @@ -96,11 +96,12 @@ After changing `.env`, run `docker compose up -d` again. ### The owner's email address -Leave the owner's email address under **Settings** empty. -Nothing on a self-hosted shard uses it yet: the shard cannot send mail, no app reads the address, and the login provider that passes it to apps is not enabled for self-hosted shards. -The hint on the Settings page that storage warnings and billing messages go to this address applies to hosted shards only. +Set your own email address under **Settings** right after pairing the first device, before you log into any app. +Apps log you in through the shard's built-in login provider, which passes them this address. +Without one, those apps create fresh accounts instead of linking to an existing account by address. -If you set one anyway, it counts as soon as you save it, because there is no confirmation mail. +A self-hosted shard cannot send mail, so the address is not confirmed by a link as on a hosted shard: it counts as soon as you save it. +Check it for typos before saving. ## What a self-hosted shard still gets from Freeshard From 6a587a275a75fa304a505cb93473c60a6a255ecb Mon Sep 17 00:00:00 2001 From: ClaydeCode Date: Thu, 19 Nov 2026 11:59:12 +0000 Subject: [PATCH 5/5] self_hosting: only some apps use the login provider Co-Authored-By: Claude Opus 5.5 --- docs/self_hosting/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/self_hosting/index.md b/docs/self_hosting/index.md index ac29a22..c06ee4d 100644 --- a/docs/self_hosting/index.md +++ b/docs/self_hosting/index.md @@ -97,7 +97,7 @@ After changing `.env`, run `docker compose up -d` again. ### The owner's email address Set your own email address under **Settings** right after pairing the first device, before you log into any app. -Apps log you in through the shard's built-in login provider, which passes them this address. +Apps that support it log you in through the shard's built-in login provider, which passes them this address. Without one, those apps create fresh accounts instead of linking to an existing account by address. A self-hosted shard cannot send mail, so the address is not confirmed by a link as on a hosted shard: it counts as soon as you save it.