Skip to main content
This guide covers the recommended installation method using Docker Compose. This ensures a consistent environment across different platforms (Linux, macOS, Windows) and simplifies dependency management.

​
Prerequisites

​
Step-by-Step Installation

1

Create a Project Directory

Create a directory for your Figranium installation and navigate into it:
2

Create docker-compose.yml

Download the ready-made deploy file that ships in the Figranium repository:
docker-compose.deploy.yml pulls the pre-built ghcr.io/figranium/figranium:latest image, so you don’t need to clone the repository or build anything locally. The repository’s plain docker-compose.yml builds the image from source instead. Use that only if you follow the Git Clone method.Alternatively, create the docker-compose.yml file yourself:
Mount the same host directory to both container paths so captures from agent runs (which write to /app/src/public/captures) and scrape runs (which write to /app/public/captures) both land on the host.
The downloaded docker-compose.deploy.yml does not set SESSION_SECRET. Add it under environment as shown above to keep sessions valid across container restarts.
3

Start with Docker Compose

Run the following command to start the application in detached mode:
This command will:
  1. Pull the Figranium Docker image from GHCR.
  2. Start the container and map the necessary ports.
  3. Mount local directories to persist your tasks, settings, and captures.
4

Access the Application

Once the container is running, open your browser and navigate to:http://localhost:11345You should see the setup screen.

​
Managing the Container

​
View Logs

To view the application logs:

​
Stop the Application

To stop the container:

​
Update the Application

To update to the newest image for your tag, pull it and restart. With the latest tag, this installs the most recent stable release. See Image tags for other release channels.

​
Image tags

Figranium publishes multi-architecture images (linux/amd64 and linux/arm64) to ghcr.io/figranium/figranium. Choose a tag based on how much stability you need: Prereleases (version tags containing -, such as v1.3.0-rc.1) never update latest and don’t get a plain version tag. The beta tag no longer receives updates. If your compose file uses beta, switch to edge for the newest builds or to latest for stable releases. To change the tag, edit the image line in docker-compose.yml, then pull and restart:

​
Verify image provenance

Every image Figranium publishes to GHCR, including edge and stable releases, has a signed build provenance attestation. The attestation proves that the Figranium GitHub Actions workflow built the image from the figranium/figranium repository. Verify it before deploying if your environment requires supply-chain checks. You need the GitHub CLI (gh), signed in with gh auth login. Run:
Replace latest with the tag you deploy, such as edge or 1.2.3. The command exits with a non-zero status if the image has no valid attestation from the figranium/figranium repository.

​
Volume Persistence

Figranium uses volume mounts to ensure your data persists even if you delete the container.
  • ./data: Stores tasks.json, proxies.json, settings.json, execution logs, the encrypted 1Password connection, and cache files. The master key and encrypted files are in this directory by default, so protect the directory and its backups. Set MASTER_KEY_FILE to a separately protected persistent path for stronger key separation.
  • ./captures: Stores screenshots and recordings. Mount this host directory to both /app/public/captures and /app/src/public/captures inside the container. Agent runs write to the src/public/captures path, while scrape runs write to public/captures. Mounting both to the same host directory ensures every capture is persisted and visible in the run’s detail view in Executions.
If you need to backup your data, simply copy these folders.

Host Specs

Review recommended CPU, RAM, and shared memory requirements before deploying.

Configuration

Explore environment variables for customizing your Figranium instance.

Multi-Arch Install

Build from source for architectures beyond linux/amd64 and linux/arm64.

Troubleshooting

Resolve common deployment and runtime issues.