Quickstart

This page gets Lumaft running on your laptop, reading real Pulumi state, with nothing deployed anywhere. When you are done you will have seen every moving part once — the image, the data volume, the two secret files, the backend credentials — which is what the environment guides assume.

Time: about fifteen minutes. Nothing here touches your infrastructure; Lumaft only reads.

What you need

• Docker. Docker Desktop on macOS or Windows, or Docker Engine with the Compose plugin on Linux. docker compose version should print a version.
• AWS credentials on this machine that can list and read your Pulumi state bucket. If aws s3 ls s3://<your-bucket>/ works in your terminal, you have them.
• Your backend details: bucket, optional prefix, region, and layout. If you are not sure, spend five minutes on Find your backend details first.
• The image digest for the release you are running, from the release record. See Deployment and setup.

Step 1: Make a working directory

mkdir -p ~/lumaft-quickstart/run && cd ~/lumaft-quickstart
chmod 700 run

Everything on this page lives here. Delete the directory when you are finished.

Step 2: Create the two secret files

Lumaft reads its first administrator password and its backend list from files, never from environment variables.

# A random password for the first administrator. Keep the output; you sign in with it.
openssl rand -base64 24 | tee run/admin-password

# The backends to observe. Replace the four values with yours.
cat > run/backends.json <<'JSON'
{
  "schemaVersion": 1,
  "backends": [
    {
      "kind": "s3",
      "id": "quickstart",
      "displayName": "Quickstart",
      "bucket": "YOUR_BUCKET",
      "prefix": "YOUR_PREFIX",
      "layout": "project-scoped",
      "region": "us-east-1",
      "forcePathStyle": false,
      "enabled": true
    }
  ]
}
JSON

chmod 600 run/admin-password run/backends.json

If your bucket has no prefix, delete the "prefix" line entirely rather than leaving it empty. If your state is in the older Pulumi layout, set "layout": "legacy"; the details page shows how to tell.

On Linux only, the container's user (ID 1000) must own the files:

sudo chown -R 1000:1000 run

Docker Desktop on macOS and Windows handles this for you.

Step 3: Export your AWS credentials

Lumaft uses the standard AWS credential chain, so it needs the same credentials your aws CLI uses. The command below writes them to a file Compose will read. It works with profiles, SSO, and assumed roles alike, and the credentials it writes are temporary.

aws configure export-credentials --format env-no-export > .env
chmod 600 .env

If you use a named profile, add --profile <name>. Re-run the command when the credentials expire; SSO credentials typically last a few hours.

Step 4: Write the Compose file

# compose.yaml
services:
  lumaft:
    image: ghcr.io/dekglas/lumaft@sha256:REPLACE_WITH_THE_RELEASE_DIGEST
    init: true
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=64m
    ports:
      - '127.0.0.1:8080:8080'
    volumes:
      - lumaft-data:/data
      - ./run:/run/lumaft:ro
    env_file:
      - .env
    environment:
      LUMAFT_LOCAL_ADMIN_PASSWORD_FILE: /run/lumaft/admin-password
      LUMAFT_BACKENDS_FILE: /run/lumaft/backends.json
      LUMAFT_ALLOW_HTTP: 'true'

volumes:
  lumaft-data:

Two lines deserve a word:

• LUMAFT_ALLOW_HTTP: 'true' lets your browser keep the session cookie over plain http://127.0.0.1. It is for this loopback-only shape. A network-reachable deployment terminates TLS instead and never sets it.
• '127.0.0.1:8080:8080' publishes the port on your machine only. Nobody else on the network can reach it.

Step 5: Start it

docker compose up --detach
docker compose logs --follow

Within a few seconds you should see startup complete. Press Ctrl+C to stop following the logs; the container keeps running. Then:

curl -fsS http://127.0.0.1:8080/api/v1/readiness

A JSON response with "status":"ready" means the database is up. It does not yet say anything about your bucket.

If the container exits instead, docker compose logs ends with one line naming the reason. Troubleshooting maps each line to its fix; the usual first-run causes are file ownership on Linux and a typo in backends.json.

Step 6: Sign in

Open http://127.0.0.1:8080 and sign in as admin with the password from Step 2.

If sign-in appears to succeed and returns you to the sign-in screen, LUMAFT_ALLOW_HTTP is missing from the Compose file. Add it, docker compose up --detach again, and retry.

Step 7: Check the backend

Open Administration → Backends. Your backend should show a successful diagnostic within a few seconds of startup.

Step 8: Look at your stacks

Open Stacks. Projects and stacks appear after the first observation cycle commits, within about a minute of startup. Open a stack to see its resources, outputs, active locks, and update history.

Then open Operations. Every update Pulumi recorded in the backend's history is there, with its outcome and resource-change counts. This is the durable record: from now on, Lumaft keeps these operations even after the backend prunes them.

The first-run readiness checklist on the Backends page will still show Persistent storage and Backup as unverified. That is correct for a laptop; the environment guides cover both.

Step 9: Stop and clean up

docker compose stop           # keeps the data volume; `docker compose start` resumes
docker compose down --volumes # removes the container and the data volume
rm -rf ~/lumaft-quickstart

The .env file holds credentials and run/admin-password holds a password; do not leave the directory behind on a shared machine.

What you just did

Next steps

• Choose an environment in Deployment and setup.
• Read Your first hour to make sense of what the console shows.
• Add your team in Users and permissions.