Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions digest.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
> coding agents (e.g. the app-repository `add-app` skill) that build and submit
> Freeshard apps. Authoritative copy of `docs.freeshard.net/developer_docs`.
>
> Generated: 2026-06-29
> Generated: 2026-11-03
> Source: github.com/FreeshardBase/documentation
> Regenerate with the repo-local `generate-digest` skill (`.claude/skills/generate-digest/`).

Expand Down Expand Up @@ -47,7 +47,8 @@ forwarded to the container/port named in `app_meta.json` `entrypoints`.
## `docker-compose.yml.template`

A normal docker-compose file plus Jinja-style `{{ ... }}` template variables that
the shard substitutes at install time. The shard runs it like `docker-compose up`.
the shard substitutes at install time, and a `secret('<name>')` helper for
generated passwords. The shard runs it like `docker-compose up`.

Minimal example:

Expand All @@ -68,7 +69,7 @@ services:
- portal # must join the portal network
```

Complex example (dependency container + env vars + shared dir):
Complex example (password-protected dependency container + env vars + shared dir):

```yaml
version: '3.5'
Expand All @@ -92,10 +93,12 @@ services:
- REDIS_HOST=my-app-redis
- BASE_URL=https://my-app.{{ portal.domain }} # app domain = <app-name>.<shard domain>
- TITLE=My app on {{ portal.short_id }}
- REDIS_PASSWORD={{ secret('redis_password') }} # generated once, then reused

my-app-redis: # extra containers named my-app-<name>
image: redis:6.2
container_name: my-app-redis
command: redis-server --requirepass {{ secret('redis_password') }} # same name = same value
volumes:
- "{{ fs.app_data }}/redis_data:/redis_data" # use fs.app_data, same dir tree as the app
networks:
Expand All @@ -122,6 +125,24 @@ Filesystem variables:
| `fs.shared` | Absolute path to the shared data directory | `/home/user/.freeshard/user_data/shared` |
| `fs.installation_dir` | Absolute path to your installation files | `/home/user/.freeshard/core/installed_apps/my-app` |

Secrets (`{{ secret('<name>') }}`, from freeshard 0.41.2):

- For values that must not be static or predictable, e.g. an internal DB password:
`- POSTGRES_PASSWORD={{ secret('db_password') }}`.
- Name is arbitrary; referencing it declares it. No `app_meta.json` entry.
- First render that references a name generates 32 chars of `[A-Za-z0-9]` and
stores it. Afterwards the same value is returned for that name: across app
updates, restarts and reinstalls. Never rotated.
- Same name → same value everywhere in the template (all containers). Different
names → different values. Scoped per app: another app's `secret('db_password')`
is a different value.
- Kept on uninstall (like app data), so a reinstall reuses it. Included in the
shard backup.
- Alphanumeric only, so safe unquoted in env vars, commands and URLs, e.g.
`postgres://my-app:{{ secret('db_password') }}@my-app-postgres/my-app`.
- Renaming a secret in a later app version yields a new value; a database
initialized with the old one will reject it. Keep names stable.

### Limitations (enforced on app-store submission)

- **Filesystem**: mount only the directories exposed via `fs.*` variables. Have a
Expand Down
54 changes: 48 additions & 6 deletions docs/developer_docs/docker_compose_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ title: The Docker-Compose Template

When starting an app, the shard simply brings up a docker-compose file just like you would with `docker-compose up`.
This file is generated during installation of the app from a `docker-compose.yml.template` that you have to provide.
The template is a normal docker-compose file with some special variables that the shard will replace with the correct values.
The template is a normal docker-compose file with some special variables that the shard will replace with the correct values,
and a `secret()` helper that fills in generated passwords.

---

Expand Down Expand Up @@ -47,7 +48,7 @@ services:
## Complex Example

Now let's look at a more complex example.
Here we have an app that depends on a redis database and has some environment variables that need to be set.
Here we have an app that depends on a password-protected redis database and has some environment variables that need to be set.
We also want to access the shared part of the filesystem where apps can store data that is shared between them.

```yaml
Expand All @@ -72,12 +73,14 @@ services:
- REDIS_HOST=my-app-redis # (3)!
- BASE_URL=https://my-app.{{ portal.domain }} # (4)!
- TITLE=My app on {{ portal.short_id }} # (5)!
- REDIS_PASSWORD={{ secret('redis_password') }} # (6)!

my-app-redis: # (6)!
my-app-redis: # (7)!
image: redis:6.2
container_name: my-app-redis
command: redis-server --requirepass {{ secret('redis_password') }} # (8)!
volumes:
- "{{ fs.app_data }}/redis_data:/redis_data" # (7)!
- "{{ fs.app_data }}/redis_data:/redis_data" # (9)!
networks:
- portal
```
Expand All @@ -90,9 +93,14 @@ services:
An app's domain name is always `<app-name>.<shard domain>`.
5. We can also use the `portal.short_id` variable to get the shard's six-digit unique identifier.
This is useful for example to set the title of the app.
6. This app need a redis database, so we add a redis container to the docker-compose file.
6. The app needs the redis password. `secret('redis_password')` generates a random password
the first time the template is rendered and returns the same value on every later render.
Read more in the section on [secrets](#secrets).
7. This app need a redis database, so we add a redis container to the docker-compose file.
The naming convention for additional containers is `my-app-<name>`, where `<name>` is the name of the container.
7. We mount a directory for redis to store its data. Note that we use `fs.app_data` just as for the app itself
8. Redis is started with the same secret as its password.
Because both containers reference the name `redis_password`, they get the same value.
9. We mount a directory for redis to store its data. Note that we use `fs.app_data` just as for the app itself
so the redis data will be stored in the same directory as the app data.

## Variables
Expand All @@ -107,6 +115,40 @@ Here is a complete list of all variables that you can use in your template.

{!developer_docs/includes/template_vars_fs.md!}

### Secrets

Some values must not be static or predictable, for example the password of a database that only your app talks to.
For these, call the `secret()` helper with a name of your choice:

```yaml
environment:
- POSTGRES_PASSWORD={{ secret('db_password') }}
```

There is nothing to declare beforehand: the name exists as soon as the template references it.
The shard handles it like this:

- The first time a template that references a name is rendered, the shard generates a random value
of 32 letters and digits (`[A-Za-z0-9]`) and stores it.
- From then on, `secret()` returns that same value for that name.
It stays the same across app updates, restarts and reinstalls, and it is never rotated.
- Every reference to the same name returns the same value, within one template and across containers.
Different names get different values.
- Secrets are scoped to your app.
Another app that uses the same name gets its own, different value.
- Secrets are kept when the app is uninstalled, just like its data,
so reinstalling the app reuses them.
They are also part of the shard's backup.

Because the value only contains letters and digits, it can go anywhere in the template without quoting or escaping,
for example inside a connection URL like `postgres://my-app:{{ secret('db_password') }}@my-app-postgres/my-app`.

Note that a secret is tied to its name.
If a later version of your app references `secret('db_pass')` where it used to say `secret('db_password')`,
it gets a new value, and a database that was set up with the old one will no longer accept it.

The `secret()` helper is available from freeshard version 0.41.2.

## Limitations

Technically, you can use any docker-compose feature in your template.
Expand Down
Loading