Skip to content

Latest commit

 

History

History
315 lines (236 loc) · 33.3 KB

docker.md

File metadata and controls

315 lines (236 loc) · 33.3 KB

Run with Docker

The reference host, src/FluentCMS.Host, is FluentCMS as one container: the Delivery and Management APIs, the authorization server and its hosted pages, and health probes. It is configured entirely by environment variables, so nothing has to be compiled to run it.

The published image

Each release pushes the image to ghcr.io/fluentcms/fluentcms, for linux/amd64 and linux/arm64, with three kinds of tag: the version, such as 1.0.0-preview.1; preview, the newest preview; and latest, the newest release that is not a preview, which comes with 1.0.0. Pin a version in production. The commands on this page name the image fluentcms, as a local build tags it; use the published name in its place:

docker pull ghcr.io/fluentcms/fluentcms:1.0.0-preview.1

The Publish workflow builds it from the tag, with the version of the packages in the host (releasing).

Build and run

Build the image from the repository root:

docker build -f src/FluentCMS.Host/Dockerfile -t fluentcms .

The Dockerfile builds for the platform it runs on, and for both linux/amd64 and linux/arm64 with docker buildx build --platform linux/amd64,linux/arm64. The SDK compiles for the target on the build machine, so no emulation is needed. A local build is version 1.0.0-dev; --build-arg VERSION=1.0.0-preview.1 gives another, as the Publish workflow does. The image is mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled-extra: no shell and no package manager, ICU and time zone data for localized content and schedules, and the non-root user app (uid 1654).

The image runs in the Production environment, which refuses to start on the defaults that are only safe for a trial. Run with nothing set, it stops before it touches the database, exits with code 1 and prints one line per refusal, each naming the setting and the key that lifts it:

  • FCMS1102: tokens would be signed with a key the server generates, because no signing certificate is configured.
  • FCMS1105: links in password reset and invitation emails would follow the request's Host, because FluentCms__PublicOrigin is not set.
  • FCMS1106: the Data Protection key ring would be stored in the database unencrypted.

Before production fixes each of them. To evaluate the image, set the public origin and lift the other two explicitly:

docker run -d --name fluentcms -p 8080:8080 -v fluentcms-data:/data \
  -e FluentCms__PublicOrigin=https://cms.example.com \
  -e FluentCms__Security__AllowGeneratedSigningKey=true \
  -e FluentCms__Security__AllowUnencryptedKeyRing=true \
  fluentcms

FluentCms__PublicOrigin is the https address you reach the instance at through the proxy that ends TLS, which sign-in needs (see before production). With no such address yet, FluentCms__Security__AllowRequestOrigin=true in its place builds links from each request. The startup report keeps listing each opt-in, as generated-signing-key, data-protection-keys-unencrypted or public-origin-unset.

It runs on SQLite, in /data/fluentcms.db, and applies the migrations on start. Keep /data on a volume, or the database goes with the container. The database is in WAL mode, so /data also holds fluentcms.db-wal and fluentcms.db-shm while the host runs: keep the three files together, and stop the container before copying them, since fluentcms.db alone misses the commits still in -wal, or take a backup while it runs with fluentcms backup (backups). Put the volume on a local disk, not a network share such as NFS, SMB or Azure Files, where SQLite's locks and the shared memory WAL needs do not work (see SQLite). GET http://localhost:8080/health/ready answers Healthy once the database and the job runner are up, and docker ps shows the container as healthy: the image's HEALTHCHECK runs the host itself with --probe, because a chiseled image has no curl.

Content types

A new instance has no content types. Give it some in one of two ways:

  • FLUENTCMS_SAMPLE=blog adds the Blog sample's types and seeds them with authors, tags and articles, in English and French. It is for trying FluentCMS out.
  • FLUENTCMS_SCHEMA=/config/schema.json loads a schema file through the fluent builder. Mount it read-only and keep it under version control:
docker run -d -p 8080:8080 -v fluentcms-data:/data -v ./schema.json:/config/schema.json:ro -e FLUENTCMS_SCHEMA=/config/schema.json fluentcms
{
  "collections": [
    {
      "name": "post",
      "localized": true,
      "fields": [
        { "name": "title", "type": "text", "required": true, "maxLength": 200, "localizable": true },
        { "name": "body", "type": "richText", "localizable": true },
        { "name": "publishedOn", "type": "dateTime", "indexed": true }
      ]
    }
  ],
  "singletons": [
    { "name": "site-settings", "fields": [ { "name": "tagline", "type": "text" } ] }
  ]
}

The format is the one GET /api/management/v1/schema/snapshot returns, so a snapshot of one instance is a schema file for another. A file with an error stops the container with every problem and its code, such as FCMS1213 for a file that is not valid JSON or has an unknown property and FCMS1203 for an unknown field type; a path that does not exist stops it with FCMS3153. Both may be set: the sample's types and the file's are then one schema.

A schema file has no compiled migrations. On SQLite the host creates and extends its tables on start: a new type, a new optional field and a new index are applied, and a change that would drop or rewrite data, such as removing a field, changing its type or adding a required field, is logged as a warning and left undone. Start records the schema history only when it applied every change and none loses data, so fluentcms schema apply still sees such a change. The startup report lists this as schema-sync-outside-development, a known choice of the image rather than a mistake. On PostgreSQL and SQL Server nothing changes the database on start; fluentcms schema apply brings the content tables up to the schema (below), and it applies on SQLite too, where it also makes the changes that start leaves undone.

Environment variables

Variable Default Meaning
FLUENTCMS_SCHEMA none The path of a schema file in the container.
FLUENTCMS_SAMPLE none blog for the Blog sample. Any other value stops the host with FCMS3152.
FluentCms__Database__Provider Sqlite Sqlite, PostgreSql or SqlServer. Another value stops the host with FCMS3150.
ConnectionStrings__FluentCms Data Source=/data/fluentcms.db The connection string. PostgreSQL and SQL Server have no default and stop the host with FCMS3151 without one.
FluentCms__PublicOrigin none The address users reach the instance at, such as https://cms.example.com. Password reset and invitation links and the issuer are built from it. See the checklist.
AllowedHosts * The host names the instance answers, separated by ;. See the checklist.
FluentCms__Security__SigningCertificate__Path and __Password none The PKCS#12 file tokens are signed with. See the checklist.
FluentCms__DataProtection__Certificate__Path and __Password none The PKCS#12 file with an RSA key that the Data Protection key ring is encrypted with. A file that cannot be read stops the host with FCMS3155. See the checklist.
FluentCms__Security__AllowGeneratedSigningKey false true accepts the token signing key the server generates (FCMS1102 otherwise).
FluentCms__Security__AllowRequestOrigin false true accepts an unset FluentCms__PublicOrigin (FCMS1105 otherwise).
FluentCms__Security__AllowUnencryptedKeyRing false true accepts the key ring stored unencrypted (FCMS1106 otherwise).
FluentCms__Email__Smtp__Host and the rest of FluentCms__Email__Smtp__* none The SMTP server that invitations and password resets go through; see email.
FluentCms__Sso__Providers__{name}__* none An OpenID Connect provider that admin users sign in with; see single sign-on.
FluentCms__Media__S3__* none Any key of the section stores new uploads in an S3 bucket, or one of an S3-compatible service such as MinIO, instead of the local disk: Bucket, Endpoint, Region, KeyPrefix, ForcePathStyle, AccessKeyId and SecretAccessKey, as the media plugin lists them. A section without a valid bucket stops the host at start.
FluentCms__OpenApi__Enabled off true serves the OpenAPI document at /openapi/v1.json and the Scalar UI at /scalar. See the API description.
ASPNETCORE_HTTP_PORTS 8080 The port the host listens on, from the base image.

Every other option is a key of the FluentCms section, written with __ for :, as host configuration lists them.

The first administrator

A new instance has no users. The image makes the first administrator with fluentcms user create, run with the same settings as the instance and, on SQLite, the same /data volume (see commands of the image). The password is read from standard input, never from an argument, so pass -i and write it to the command, or pass -it, leave out --password-stdin and type it twice at the prompt, which does not echo it:

docker run --rm -v fluentcms-data:/data fluentcms fluentcms migrate
docker run --rm -i -v fluentcms-data:/data fluentcms \
  fluentcms user create --email ada@example.com --role "Super Admin" --password-stdin < ada-password.txt

A command applies no migration, and the Super Admin role comes with the system migration, so a new database is migrated first, with fluentcms migrate or one start of the instance.

The user is active, with the address as its user name, and signs in through the hosted login page at once. user create exists in the host only: over the Management API a user is invited, so that an API key alone never sets a password.

An instance that is set up from its environment alone, with no step that runs a command, invites its first administrator instead, and an invitation is sent by someone who can manage users. The operator is a confidential client with the Super Admin role, registered from the environment:

-e FluentCms__Clients__Applications__ops__Secret=<from your secret store>
-e FluentCms__Clients__Applications__ops__Scopes__0=management
-e "FluentCms__Clients__Applications__ops__Roles__0=Super Admin"

It gets a token with the client credentials grant at /connect/token (grant_type=client_credentials, client_id=ops, its secret, scope=management) and invites the first administrator with POST /api/management/v1/invitations { "email": "ada@example.com", "roleIds": ["<id of Super Admin from GET /roles>"] }. The invitation is emailed, so set up SMTP first. The person follows the link, picks a user name and a password on the hosted page, and signs in from then on through the hosted login page with any client registered with RedirectUris. Remove the operator's variables, or keep its secret in a secret store, once it is no longer needed.

The Delivery API is closed until a role allows reading: create a role with content.{type}.read and a Delivery key bound to it with POST /api/management/v1/api-keys { "name", "class": "delivery", "roleId" }, or with fluentcms apikey create --name site --class delivery --role <role>, or grant those permissions to the site's Public role for anonymous reads.

Single sign-on

Admin users can sign in with Microsoft Entra ID, Okta, Keycloak or any other OpenID Connect provider, configured from the environment. Register the image's public address followed by /account/sso/{name} as the redirect URI at the provider, such as https://cms.example.com/account/sso/corp; with FluentCms__PublicOrigin set, the instance sends exactly that. For Entra ID:

-e FluentCms__Sso__Providers__corp__Preset=EntraId
-e FluentCms__Sso__Providers__corp__TenantId=<directory id>
-e FluentCms__Sso__Providers__corp__ClientId=<application id>
-e FluentCms__Sso__Providers__corp__ClientSecret=<from your secret store>
-e FluentCms__Sso__Providers__corp__DefaultRole=Author
-e FluentCms__Sso__Providers__corp__RoleMappings__0__Group=<object id of the admins group>
-e "FluentCms__Sso__Providers__corp__RoleMappings__0__Role=Super Admin"

Okta takes Preset=Okta and Domain (with AuthorizationServerId for a custom authorization server), Keycloak Preset=Keycloak, BaseUrl and Realm, and any other provider Authority. A first sign-in creates the user with DefaultRole and the roles its groups map to, and those mapped roles follow the groups at every sign-in; a mapping that names Super Admin, as above, gives the first administrator without an invitation. FluentCms__Sso__DisableLocalLogin=true hides the password form and refuses password sign-ins; invited users then accept their invitation through the provider, whose address for them must be the one invited. LinkExistingUsers=true on a provider links an existing user at its first sign-in through it when the token says the address is verified. A provider's own multi-factor claim counts for a role that requires two-factor only with TrustMfaClaim=true on that provider. See single sign-on for every setting.

The API description

The image serves no OpenAPI document and no Scalar UI, because the document names every content type, field, component and block of the schema to anyone who can reach it, whatever that caller may read. FluentCms__OpenApi__Enabled=true serves the document of the instance at /openapi/v1.json and the Scalar UI at /scalar/, which is handy on a private network or while evaluating. Before exposing them more widely, put them behind an authorization policy: a host of your own built on AddFluentCms() does that with app.MapFluentCmsOpenApi().RequireAuthorization("docs"), and with the image, keep them off or limit who reaches those paths at the proxy. See OpenAPI and the Scalar UI.

Before production

  • TLS. The authorization server, and so sign-in, answers HTTPS only, and the image listens on plain HTTP. Put it behind a proxy that ends TLS and forward the scheme with FluentCms__ReverseProxy__ForwardedHeaders__Enabled=true and the proxy's address in FluentCms__ReverseProxy__ForwardedHeaders__KnownProxies__0 or its network in KnownNetworks__0; see reverse proxy.
  • Public address. Set FluentCms__PublicOrigin to the address users reach the instance at, such as https://cms.example.com, with the path base when there is one. Password reset and invitation links and the issuer are then built from it, and tokens issued before it was set stop working; without it they follow the request's host, so a request with a forged Host header gets a link to the attacker's host emailed to a real user. That is why the host refuses to start without it (FCMS1105) unless FluentCms__Security__AllowRequestOrigin=true.
  • Host names. Set AllowedHosts to the host names of the instance, such as AllowedHosts=cms.example.com;localhost, so that the instance answers no other host and a proxy's X-Forwarded-Host is applied only for those. Keep localhost in the list, or the HEALTHCHECK, which calls localhost, is turned away with 400.
  • Health probes. /health/live and /health/ready answer without credentials, because the HEALTHCHECK and an orchestrator's probes call them. They never look up an API key and are limited per client address, apart from the API (FluentCms__RateLimits__Health__PermitLimit, 1200 a minute, far above what an orchestrator sends), so a flood of probes stays cheap. Still let only the orchestrator and the load balancer reach /health where you can, for example with a rule at the proxy or a network policy; the HEALTHCHECK calls localhost inside the container and needs no route from outside.
  • Signing key. Mount a PKCS#12 (.pfx) file with an RSA key read-only, such as -v ./certs:/certs:ro, and set FluentCms__Security__SigningCertificate__Path=/certs/signing.pfx and FluentCms__Security__SigningCertificate__Password from your secret store. Drop FluentCms__Security__AllowGeneratedSigningKey from an evaluation setup, so that settings that lose the certificate stop the host (FCMS1102) instead of falling back to the generated key.
  • Key ring. The Data Protection key ring protects the generated keys, the sign-in cookie and reset tokens, and is kept in the database, so a reader of the database could forge a sign-in. Mount a second PKCS#12 file with an RSA key and set FluentCms__DataProtection__Certificate__Path=/certs/ring.pfx and FluentCms__DataProtection__Certificate__Password from your secret store; the ring is then encrypted for that certificate, and FluentCms__Security__AllowUnencryptedKeyRing can go. Keys written before stay readable. With Azure Key Vault, keep the certificate there and let the platform mount it as that file, such as the Secrets Store CSI driver on AKS or a secret volume on Azure Container Apps. To wrap the ring with a Key Vault key instead, build a host of your own on AddFluentCms with ProtectKeysWithAzureKeyVault, as the authorization server shows.
  • Email. Set FluentCms__Email__Smtp__Host, __Port, __UserName, __Password and __From; without them invitations and password resets fail with FCMS3008.
  • Several instances. The image keeps the Delivery output cache and the member mail limit, one mail a minute of each kind to an address, in memory, one of each per instance. Behind a load balancer, a publish then evicts the copies of one instance, and the others serve theirs until FluentCms__Delivery__Cache__OutputCacheDuration runs out; and each instance sends an address its own mail. To run several, build a host of your own on AddFluentCms that registers a shared IOutputCacheStore and a shared IDistributedCache, such as Redis (provider slots). Once email is set up, the startup report lists member-mail-limit-per-instance while the mail limit is per instance; one instance needs neither.

Together, behind a proxy that ends TLS:

docker run -d --name fluentcms -p 8080:8080 -v fluentcms-data:/data -v ./certs:/certs:ro \
  -e FluentCms__PublicOrigin=https://cms.example.com \
  -e "AllowedHosts=cms.example.com;localhost" \
  -e FluentCms__ReverseProxy__ForwardedHeaders__Enabled=true \
  -e FluentCms__ReverseProxy__ForwardedHeaders__KnownProxies__0=<address of the proxy> \
  -e FluentCms__Security__SigningCertificate__Path=/certs/signing.pfx \
  -e FluentCms__Security__SigningCertificate__Password=<from your secret store> \
  -e FluentCms__DataProtection__Certificate__Path=/certs/ring.pfx \
  -e FluentCms__DataProtection__Certificate__Password=<from your secret store> \
  -e FluentCms__Email__Smtp__Host=smtp.example.com \
  -e "FluentCms__Email__Smtp__From=FluentCMS <cms@example.com>" \
  fluentcms

The startup report, logged at start and served at GET /api/management/v1/system/diagnostics, lists each of these while it is still a default or lifted by an opt-in. Keep the database and its backups as secrets all the same: they still hold the key that encrypts codes and refresh tokens, and the sessions.

Other databases

FluentCms__Database__Provider=PostgreSql or SqlServer with ConnectionStrings__FluentCms runs on that server. Those providers do not migrate on start by default, so apply the migrations before the host starts, with fluentcms migrate (below) or with FluentCms__Database__MigrateOnStartup=true on one instance. On SQL Server the system migrations turn READ_COMMITTED_SNAPSHOT on unless it is on already, as on Azure SQL Database. That needs ALTER permission on the database, and it disconnects the database's other sessions once (ADR 0005). They never create content tables from the schema on start: with FLUENTCMS_SCHEMA or FLUENTCMS_SAMPLE, run fluentcms schema apply after fluentcms migrate (below), and a host that starts before it stops with FCMS1301, which names the command. PostgreSQL 15 and SQL Server 2019 and 2025 are tested providers (#2711). The webhooks and media plugins hold a migration set for each of these providers (plugin migrations).

Migrate before the host starts

The image runs the commands of the host as well as the host: arguments that start with fluentcms run that command and end the container with its exit code (0, 1 for a failure, 2 for bad usage), and nothing listens, runs jobs or seeds. An init container or a deploy step applies the migrations of every stream with the same image and settings as the host:

docker run --rm \
  -e FluentCms__Database__Provider=PostgreSql \
  -e "ConnectionStrings__FluentCms=Host=db;Database=fluentcms;Username=fluentcms;Password=<from your secret store>" \
  fluentcms fluentcms migrate

fluentcms migrate --check lists what is pending and exits with 1 when anything is, which suits a readiness gate. fluentcms migrations list shows the applied and pending migrations of each stream, and fluentcms migrations script --idempotent --output /out/migrate.sql writes the SQL for a database that only an administrator may change (PostgreSQL and SQL Server; mount /out). The host's logs go to standard output with the command's output, so set Logging__Console__LogToStandardErrorThreshold=Trace to keep them apart. A command needs none of the Production settings of the host above, since it serves nothing. Instances that migrate one database at once apply each migration once, but on SQL Server the first migration of a new database turns READ_COMMITTED_SNAPSHOT on, which disconnects the database's other sessions, so a second run that waits meanwhile fails and succeeds when it runs again: run one migrate step per deploy, or let it restart. In Kubernetes:

initContainers:
  - name: migrate
    image: fluentcms
    args: ["fluentcms", "migrate"]
    envFrom:
      - secretRef:
          name: fluentcms-database

Administer an instance

The same image runs the commands that administer the instance, as the system, with the origin Cli in the activity log:

Command Does
fluentcms apikey create --name <name> --class <delivery|preview|management> --role <name> [--site <slug>] [--types <list>] [--expires <date>] prints the new key once, alone on standard output
fluentcms apikey list, fluentcms apikey revoke <id> lists the keys, revokes one
fluentcms user create --email <address> --role <name> [--site <slug>] [--password-stdin] an active administrator (above)
fluentcms user invite --email <address> --role <name> [--site <slug>] emails an invitation
fluentcms user reset-password --email <address> [--password-stdin] emails a reset link, or sets the password read from standard input
fluentcms user add-role --email <address> --role <name> [--site <slug>] gives a role
fluentcms jobs list [--queue <name>] [--status <status>], fluentcms jobs retry <id> lists the newest jobs, queues a dead-lettered one again
fluentcms jobs run <name> [--inline] queues a run of a recurring job, or runs it in the command's process with one attempt
fluentcms seed [--name <seeder>] runs the seeders that are not applied at their version

List commands print a table, and one line of JSON in the shape of the Management API with --json. The invitation and reset emails link to FluentCms__PublicOrigin, which these commands need (FCMS3354 otherwise). Set Logging__Console__LogToStandardErrorThreshold=Trace so that standard output holds only what the command prints, such as the key of apikey create. What a command writes to the activity log reaches it through the outbox, which a running instance delivers.

The fluentcms tool runs apikey, user invite, user add-role, jobs list and jobs retry against a running instance too, with --url https://cms.example.com and a management API key in FLUENTCMS_TOKEN (or --token, which a process list shows for as long as the command runs). They call the Management API as that key, so a key without the permission is refused with the API's problem and exit code 1. Every command with --url warns with FCMS3363 when the key goes over plain http to another machine, and a usage error never repeats the value after --token; the tool reads no @file response file, so put the key in FLUENTCMS_TOKEN rather than in one. Ctrl+C cancels such a command, which then has 10 seconds to clean up: an export removes the file it was writing, and mcp ends its session.

fluentcms mcp --url https://cms.example.com is a proxy from standard input and output to the instance's /mcp, for an MCP client that speaks stdio only; a refused key ends it with FCMS3362 on standard error. It runs for the whole session of the editor, so give it the key in the env of the client's configuration rather than in --token, which would stay in the process list all that time:

{
  "mcpServers": {
    "fluentcms": {
      "command": "fluentcms",
      "args": ["mcp", "--url", "https://cms.example.com"],
      "env": { "FLUENTCMS_TOKEN": "fcms_mk_..." }
    }
  }
}

The configuration file then holds the key, so keep it out of source control, or use the client's own way to read a secret into env where it has one.

Apply a schema file

With FLUENTCMS_SCHEMA or FLUENTCMS_SAMPLE the content types are data, so they have no migrations. fluentcms schema apply, run after fluentcms migrate with the same image and settings, compares the schema with the content tables, applies the difference and records the schema in the schema history; when nothing differs it changes nothing and exits with 0. It is what records the schema history for these hosts, the first row of a new database too: fluentcms migrate and a start leave the newest row as it is, so the next schema apply still sees what a new schema removes or renames. It refuses while the system or a plugin stream has a pending migration (FCMS3336), which is why it runs second:

initContainers:
  - name: migrate
    image: fluentcms
    args: ["fluentcms", "migrate"]
    envFrom:
      - secretRef:
          name: fluentcms-database
  - name: schema-apply
    image: fluentcms
    args: ["fluentcms", "schema", "apply"]
    env:
      - name: FLUENTCMS_SCHEMA
        value: /config/schema.json
    envFrom:
      - secretRef:
          name: fluentcms-database
    volumeMounts:
      - name: schema
        mountPath: /config
        readOnly: true

A new type, field or index is applied, and so is a renamed field that lists its old name in formerNames, which keeps its values, its columns in a component and the references cms_reference keeps under its path. A required field added to a table with rows gets an empty value in them: '' for text, the empty document for rich text. A change that loses data, such as a removed type or field or a changed field type, is listed and refused with FCMS3337, and nothing is applied, unless --allow-destructive is given. So is a renamed field whose values are kept in JSON under its old name: a field of a block, or of a component that is repeated or sits in a block. The tables of a plugin are not a removed type's: a plugin that the image does not hold, or that the host no longer adds, keeps its tables while the database has its history table cms_{plugin}__migrations, and the run lists them under Left alone:. The operations of a run are one transaction, so a database that refuses one keeps none (FCMS3339); on SQLite a table rebuild commits what came before it, which the next run then leaves out, and runs started together apply each operation once.

--dry-run prints the operations and applies nothing, and exits with 1 when the run would be refused. --script --output /out/schema.sql writes the SQL for the database as it is now and applies nothing, for a database that only an administrator may change; the next fluentcms schema apply finds nothing to do and records the schema, and after a script with a change that loses data it needs --allow-destructive too. A host built with content migrations of its own is refused with FCMS3335, since its content tables belong to those migrations.

For local development, compose.yaml at the root of the repository runs PostgreSQL and MinIO at the versions the tests use; see Local development.

Compose with PostgreSQL and MinIO

src/FluentCMS.Host/compose.yaml runs the image on PostgreSQL 15, with its media in a MinIO bucket and the Blog sample, set up from the environment alone. Its services:

  • postgres, with its data in the volume postgres and a health check.
  • minio, with its data in the volume minio, and minio-init, which makes the bucket fluentcms-media and a MinIO user allowed that bucket only, and ends. The host signs its requests with that user, not the root user.
  • migrate, which runs fluentcms migrate, and then schema-apply, which runs fluentcms schema apply, with the image and the database settings of the host. The image runs one command per container and has no shell, so they are two services. Each ends, and applies nothing when nothing is pending, so every up runs them.
  • cms, the host, which starts once migrate and schema-apply have ended with 0, minio-init has made the bucket, and postgres and minio are healthy. It listens on http://localhost:8080, on the machine's loopback address only.

The passwords and keys come from .env beside the compose file, which .gitignore keeps out of the repository. Copy .env.example, fill in every empty value, and start from that directory:

cd src/FluentCMS.Host
cp .env.example .env
docker compose up -d --build

docker compose refuses to start while a value is missing or empty, and names it. The example also sets the two opt-ins of an evaluation, FLUENTCMS_ALLOW_GENERATED_SIGNING_KEY and FLUENTCMS_ALLOW_UNENCRYPTED_KEY_RING; without them the host stops with FCMS1102 and FCMS1106. The public origin is https://localhost and AllowedHosts is localhost unless FLUENTCMS_PUBLIC_ORIGIN and FLUENTCMS_ALLOWED_HOSTS say otherwise. GET http://localhost:8080/health/ready answers Healthy once the database, the job runner and the bucket (media-storage) answer. PostgreSQL takes its password when it creates its volume, so a changed FLUENTCMS_POSTGRES_PASSWORD needs docker compose down -v, which deletes the data too.

To run the published image instead of building one, set FLUENTCMS_IMAGE=ghcr.io/fluentcms/fluentcms:1.0.0-preview.1 in .env and start without a build; migrate, schema-apply and cms all run it:

docker compose pull
docker compose up -d --no-build

Make the first administrator and a deploy key with the image while the services run. --no-deps keeps run from running migrate and the other steps again. The key is printed alone on standard output:

docker compose run --rm -T --no-deps cms fluentcms user create --email ada@example.com --role "Super Admin" --password-stdin < ada-password.txt
docker compose run --rm -T --no-deps cms fluentcms apikey create --name deploy --class management --role "Super Admin"

The key works over plain http at once. Signing in on the hosted pages needs https, so it waits for the proxy below. The Compose workflow in CI starts this file with throwaway values on every push to main and to a feature/* branch, signs an administrator in through the hosted pages with a proxy's forwarded headers, publishes an article through the Management API, reads it through the Delivery API, and uploads an image that it reads back from MinIO. Actions → Compose → Run workflow with an image, such as ghcr.io/fluentcms/fluentcms:1.0.0-preview.1, runs the same test on the published image instead of a build.

What to change for production:

  • Certificates. Remove the two opt-ins from .env, mount the signing and key ring certificates into cms and set their paths and passwords, as before production shows.
  • Address and TLS. Put a proxy that ends TLS in front of cms, set FLUENTCMS_PUBLIC_ORIGIN to its https address and FLUENTCMS_ALLOWED_HOSTS to its host name with localhost, and forward the scheme (reverse proxy).
  • Content types. Replace FLUENTCMS_SAMPLE: blog in x-host-environment with FLUENTCMS_SCHEMA and mount the schema file into migrate, schema-apply and cms, since each of them loads it. A change that loses data stops schema-apply with FCMS3337, and cms then does not start; add --allow-destructive to its command only for that run.
  • Storage. For S3 or another managed service, drop minio and minio-init and set the FluentCms__Media__S3__* keys of cms to its bucket and an access key limited to it.
  • Email, backups and the image. Set the SMTP keys, back up the database with pg_dump (backups; fluentcms backup refuses on PostgreSQL) and the bucket with the tools of its service, and set FLUENTCMS_IMAGE to the published image at a version, or to an image of your registry with its tag.