tstaehli84/filemaker-server repository overview

⁠FileMaker Server for Docker

⁠Contents

• Quickstart⁠
• How the image works⁠
• Choose an image⁠
• Docker run⁠
• Docker Compose⁠
• Administrator environment variables⁠
• Storage and data retention⁠
• Bind mounts⁠
• Backups and recovery⁠
• Upgrade routes⁠
• Upgrade with Docker run⁠
• Upgrade with Compose⁠
• Troubleshooting⁠

⁠Quickstart

FileMaker Server 21, 22, and 26 on Ubuntu, with persistent storage and startup checks for upgrades. Images support AMD64 and ARM64; Docker selects the matching architecture.

Image: tstaehli84/filemaker-server⁠

⁠Before you start

First-start installation requires internet access. Configure your FileMaker Server license after setup.

Both examples deploy 26.0.3-ubuntu24 using the same persistent storage. Use either Docker run or Compose.

⁠Option 1: Docker run

docker run -d \
  --name fms \
  --hostname fms \
  --privileged \
  --restart unless-stopped \
  --stop-timeout 135 \
  -p 80:80 \
  -p 443:443 \
  -p 5003:5003 \
  -v "fms-data:/opt/FileMaker/FileMaker Server" \
  -v "fms-state:/var/lib/fms-docker" \
  tstaehli84/filemaker-server:26.0.3-ubuntu24

See Startup and access⁠ for installation progress and connection details.

⁠Option 2: Docker Compose

Use compose.yaml⁠:

name: fms
services:
  fms:
    image: tstaehli84/filemaker-server:26.0.3-ubuntu24
    container_name: fms
    hostname: fms
    privileged: true
    restart: unless-stopped
    stop_grace_period: 135s
    ports:
      - "80:80"
      - "443:443"
      - "5003:5003"
    volumes:
      - fms-data:/opt/FileMaker/FileMaker Server
      - fms-state:/var/lib/fms-docker
volumes:
  fms-data:
    name: fms-data
  fms-state:
    name: fms-state

docker compose up -d
docker compose logs -f fms

⁠Startup and access

The first start takes several minutes: the container installs FileMaker Server and its dependencies. A running container may still be installing.

Check the container’s Logs tab in Docker Desktop, or follow progress from the terminal:

# Docker run
docker logs -f fms

# Docker Compose
docker compose logs -f fms

Wait for the startup confirmation:

[FMS] READY: FileMaker Server startup completed successfully; fmshelper.service is running.

• Admin Console: open https://localhost/admin-console⁠ when Docker is on your computer. For another computer, replace localhost with the Docker host’s IP address or DNS name.
• Initial login: username admin, password 1234, PIN 0000 for a fresh installation unless overridden with administrator environment variables⁠. Change the password in the admin console, then configure your license and TLS certificate. Upgraded installations retain their saved credentials.
• FileMaker Pro: add the same host address in Hosts. The connection uses port 5003.

The examples publish ports on all host interfaces. Restrict access as appropriate and replace the initial credentials and certificate before exposing the server to untrusted networks.

Check status with docker ps or docker compose ps. healthy confirms startup and helper-service checks; also verify Admin Console login and your hosted databases.

⁠Storage and upgrades

The examples save the whole FileMaker Server folder in fms-data and startup history in fms-state. Keep both volumes when replacing or upgrading a container. Persistent storage is not a backup.

Do not run docker compose down -v or delete these volumes unless you intend to erase the server’s saved files.

For upgrades, select a specific release with the same Ubuntu suffix, back up both volumes while stopped, then recreate the container using the original mounts. Downgrades and in-place Ubuntu changes are blocked.

The sections below cover image tags, container management, upgrade routes, volumes and bind mounts, backups, rollback, and troubleshooting.

⁠How the image works

FileMaker Server is installed from the bundled package at container startup. Services run under systemd and require privileged: true in Compose or --privileged with Docker run.

First startup takes several minutes and requires internet access for package metadata and dependencies. Monitor it in Docker Desktop’s container Logs tab or from the terminal:

# Docker run:
docker logs -f fms
# Compose:
docker compose logs -f fms

Messages beginning with [FMS] describe installation, configuration restoration, upgrade checks, and errors. Wait for:

[FMS] READY: FileMaker Server startup completed successfully; fmshelper.service is running.

The health status remains starting while installation runs. Successful startup and an active helper service produce healthy; startup failures produce unhealthy. Health does not prove that every database is open or that authentication works. Check Admin Console, FileMaker Pro, schedules, licensing, and web features you use.

Restarting the same container skips installation when the exact package is already installed. A replacement container has a new package database and installs the selected package using the saved configuration. Even replacing a container with the same image can therefore take time.

⁠Choose an image

All examples use Docker Hub:

tstaehli84/filemaker-server:26.0.3-ubuntu24

The tag combines the FileMaker release and container OS: 26.0.3-ubuntu24 selects FileMaker Server 26.0.3 on Ubuntu 24.04.

Tags omit the installer’s final build number: 26.0.3.309 becomes 26.0.3. FileMaker 21 has Ubuntu 22 variants only; 22 and 26 can have Ubuntu 22 and 24 variants. Availability depends on which images have been published.

Pin the release and Ubuntu variant for production deployments, for example 26.0.3-ubuntu24.

⁠Docker run

Use the Docker run example⁠ with both persistent mounts. The image requires privileged mode and uses a 135-second shutdown timeout for graceful FileMaker service shutdown.

⁠Docker Compose

Use the supplied compose.yaml⁠:

docker compose up -d fms
docker compose logs -f fms

For additional server instances, assign unique container names, volume names, hostnames, and host ports. Each instance must have its own FileMaker storage and startup state.

⁠Administrator environment variables

Set these optional variables before the first installation to choose the Admin Console credentials:

Each supplied value replaces the matching field in a temporary assisted-install file; the bundled template is unchanged. You can set any combination of the variables. Values must be on a single line, and ADMIN_PIN must contain exactly four digits.

These variables apply only to a fresh installation with no saved server configuration. On restarts, replacement containers using existing configuration, and upgrades, existing credentials are preserved. Changing these variables does not reset an existing password, rename the administrator, or change its PIN.

⁠With Docker Compose

Add an environment mapping under the fms service in your Compose file, alongside image, ports and volumes:

name: fms
services:
  fms:
    # Keep the other service settings from the Quickstart.
    environment:
      ADMIN_USER: "myadmin"
      ADMIN_PWD: "Choose-A-Strong-Password!42"
      ADMIN_PIN: "0123"

Quote the PIN to retain leading zeroes. For a literal $ entered directly in Compose YAML, write $$.

Alternatively, reference a .env file beside compose.yaml:

    environment:
      ADMIN_USER: ${ADMIN_USER:-}
      ADMIN_PWD: ${ADMIN_PWD:-}
      ADMIN_PIN: ${ADMIN_PIN:-}

Example .env contents:

ADMIN_USER=myadmin
ADMIN_PWD='Choose-A-Strong-Password!42'
ADMIN_PIN=0123

The environment mapping is required: a .env file alone does not pass these variables into the container. Then start the service with docker compose up -d fms.

⁠With Docker run

Add these options to the Quickstart's docker run command, before the image name:

  -e ADMIN_USER='myadmin' \
  -e ADMIN_PWD='Choose-A-Strong-Password!42' \
  -e ADMIN_PIN='0123' \

Choose your own values before starting the fresh server. Keep credential files out of version control; Docker environment inspection can reveal supplied values.

⁠Storage and data retention

Choose either of the following storage layouts. Both retain server data and startup history across container replacements; the difference is whether application files are retained alongside your configuration.

⁠Option 1: Two mounts for the whole server and startup state

This is the layout used in the Quickstart. It is convenient for backups and same-Ubuntu image upgrades because the entire FileMaker Server folder is retained.

⁠Option 2: Individual mounts for data and configuration

Mount the persistent folders separately, leaving FileMaker application binaries and other installer-managed files in the container. This gives more control over what is restored during a migration, particularly when moving to a different Ubuntu release: the destination installer creates its own application files, while selected data and compatible configuration can be restored separately.

For Compose, replace the Quickstart's volume mappings and top-level declarations with:

name: fms
services:
  fms:
    # Keep the image, ports and other service settings from the Quickstart.
    volumes:
      - fms-server-data:/opt/FileMaker/FileMaker Server/Data
      - fms-cstore:/opt/FileMaker/FileMaker Server/CStore
      - fms-wpeconf:/opt/FileMaker/FileMaker Server/Web Publishing/publishing-engine/conf
      - fms-logs:/opt/FileMaker/FileMaker Server/Logs
      - fms-state:/var/lib/fms-docker
volumes:
  fms-server-data:
    name: fms-server-data
  fms-cstore:
    name: fms-cstore
  fms-wpeconf:
    name: fms-wpeconf
  fms-logs:
    name: fms-logs
  fms-state:
    name: fms-state

For Docker run, replace the two Quickstart mounts with:

  -v "fms-server-data:/opt/FileMaker/FileMaker Server/Data" \
  -v "fms-cstore:/opt/FileMaker/FileMaker Server/CStore" \
  -v "fms-wpeconf:/opt/FileMaker/FileMaker Server/Web Publishing/publishing-engine/conf" \
  -v "fms-logs:/opt/FileMaker/FileMaker Server/Logs" \
  -v "fms-state:/var/lib/fms-docker" \

Plug-ins, custom web files and other files outside these mounted folders need separate mounts or a documented reinstallation/restore procedure. In particular, check Database Server/Extensions and custom files under HTTPServer/htdocs.

Individual mounts do not enable an in-place Ubuntu upgrade. The startup OS check still blocks changing Ubuntu while reusing the existing installation and state. Use a separate migration into fresh destination storage, following the destination FileMaker version's supported restore procedures. Restore only compatible data/configuration and reinstall compatible plug-ins; do not remove or edit the original OS marker to bypass the check. See Upgrade routes⁠.

⁠FileMaker folder contents

The following paths are relative to /opt/FileMaker/FileMaker Server. Option 1 covers all of them through the whole-server fms-data mount. With Option 2, the Data, CStore, web publishing configuration and Logs mounts cover the corresponding rows; plug-ins and custom web files need separate handling.

The full-folder mount also retains the remaining application directories and custom files under the server root. Persistence does not make installer-managed files immutable: an upgrade can replace application files and update configuration. Keep a stopped snapshot for recovery of the pre-upgrade state.

⁠Startup state

/var/lib/fms-docker is retained separately in fms-state:

For same-Ubuntu recovery, restore startup state from the same snapshot as the FileMaker folder or individual persistent folders. It contains no hosted databases, but is required to preserve installation history and upgrade checks.

⁠Bind mounts

To use host directories instead of named volumes, replace the service’s volumes section with:

    volumes:
      - "/srv/fms/data:/opt/FileMaker/FileMaker Server"
      - "/srv/fms/state:/var/lib/fms-docker"

Remove the unused top-level volume declarations. Both directories must be writable by the container’s FileMaker services. Use empty directories for a fresh installation, or restore the server folder and matching startup state from the same stopped snapshot.

For Docker run, use:

  -v "/srv/fms/data:/opt/FileMaker/FileMaker Server" \
  -v "/srv/fms/state:/var/lib/fms-docker" \

⁠Backups and recovery

Before each upgrade or migration, make sure to use FileMaker Server’s scheduled backups for databases, with copies stored outside the Docker host.

⁠Upgrade routes

At startup, the image validates the target package against saved version and Ubuntu markers, then installs using the existing FileMaker preferences.

In-place upgrades must retain the container’s Ubuntu release.

The image’s checks prevent certain unsafe operations; they do not validate every Claris-supported upgrade route. Consult the Claris upgrade instructions for your source and destination release, licensing, and client compatibility before choosing a route. Use intermediate versions where required.

To change Ubuntu versions, plan a separate migration into fresh storage using the destination version’s supported FileMaker backup/restore and configuration procedures. Reusing the existing volumes under a different Ubuntu tag is blocked. Do not remove the OS marker to bypass this protection.

⁠Upgrade with Docker run

The example below assumes your container is named fms and uses the two Quickstart volumes. Choose the destination tag with the same Ubuntu suffix as your current server. For an Ubuntu 24 server moving to 26.0.3:

1. Download the target image while the existing server is still available:

   docker pull tstaehli84/filemaker-server:26.0.3-ubuntu24
   

   Copy

2. Make a FileMaker backup, then stop the container:

   docker stop fms
   

   Copy

3. Take a complete stopped-server snapshot, including both volumes and any custom mounts.

4. Remove the stopped container:

   docker rm fms
   

   Copy

5. Run the Quickstart Docker run command⁠ with the destination image tag, keeping the same two volume names, hostname, ports, and any custom mounts/options from your original server.

6. Follow docker logs -f fms. Allow time for installation. After READY, verify Admin Console login, hosted databases, client read/write, backup schedules, license, certificates, and any web services or plug-ins you use.

⁠Upgrade with Compose

1. Confirm the current image tag in compose.yaml. Select the destination release on the same Ubuntu version.

2. Make a FileMaker backup and stop the service:

   docker compose stop
   

   Copy

3. Take a complete stopped backup of both persistent volumes and all custom paths. Save the original Compose configuration with it.

4. Change only the image: tag in compose.yaml to the selected destination, for example:

   image: tstaehli84/filemaker-server:26.0.3-ubuntu24
   

   Copy

5. Download the image and recreate the service:

   docker compose pull fms
   docker compose up -d fms
   docker compose logs -f fms
   

   Copy

6. Wait for READY and check docker compose ps. Verify login, hosted databases, client read/write, schedules, backups, license, TLS, and your integrations.

Keep volume names and paths unchanged. If installation fails, inspect the logs before recovery; persistent files may already have been modified.

⁠Troubleshooting

⁠The container is running, but I cannot connect

Check the logs first. First startup or a replacement-container installation may still be running. Look for READY or an ERROR message. Check docker ps / docker compose ps, verify port mappings, and use the Docker host’s address rather than the container’s internal IP.

⁠Installation fails or health is unhealthy

Inspect recent logs:

docker logs --tail 200 fms
# Or:
docker compose logs --tail 200 fms

For detailed installation and service output:

# Docker run:
docker exec fms journalctl -u installcheck.service --no-pager
docker exec fms systemctl status fmshelper.service --no-pager
# Compose:
docker compose exec fms journalctl -u installcheck.service --no-pager
docker compose exec fms systemctl status fmshelper.service --no-pager

Check free disk space, network access, mount permissions, and the first error above the final failure summary. A failed health check does not by itself restart or stop the container; it stays available for investigation.

⁠“Refusing container OS change” or “Refusing downgrade”

You selected an incompatible tag for the saved storage. Select a compatible same-Ubuntu image, or restore the complete corresponding backup for rollback. Do not edit the stored markers to force startup.

⁠“Existing data found without server preferences”

Startup found saved data but no usable Data/Preferences/dbs_config.xml. This can indicate incomplete migration or missing storage. Stop and check that the correct full server folder and matching state are mounted; restore a complete backup rather than initializing over existing files.

⁠“Existing installation has no OS marker”

This can occur with installations created before the OS guard existed, or if their state was not preserved. Startup refuses to guess the original Ubuntu version.

First identify the original image and confirm its Ubuntu release, for example:

# Replace ORIGINAL_IMAGE with the original image reference.
docker run --rm --entrypoint cat ORIGINAL_IMAGE /etc/os-release

Stop the server and take a complete backup. For Compose, select an image matching that confirmed original Ubuntu release. Only for a confirmed Ubuntu 22.04 installation, initialize the missing marker with:

docker compose run --rm --no-deps --entrypoint /bin/bash fms -c '
  set -eu
  . /etc/os-release
  test "$ID:$VERSION_ID" = ubuntu:22.04
  marker=/var/lib/fms-docker/os-version
  test ! -e "$marker"
  umask 077
  printf "%s\n" ubuntu:22.04 > "$marker"
'