Install with Docker

Run Linkr from the images published on Docker Hub: one Compose file, one secret key, one command.

Summary

One file to download, one key to generate, one command: Linkr is running, with every feature. No repository to clone, no code to compile. This is the recommended method, to try Linkr as well as to deploy it on a server.

Requirements

Docker: Docker Desktop on Mac and Windows, Docker Engine on Linux.
About 1 GB of disk space.

Installation

Open a terminal (Terminal on macOS, PowerShell on Windows) in a folder dedicated to Linkr.

Download the Compose file

curl -O https://framagit.org/interhop/linkr/linkr/-/raw/main/docker/docker-compose.hub.yml

Invoke-WebRequest -Uri https://framagit.org/interhop/linkr/linkr/-/raw/main/docker/docker-compose.hub.yml -OutFile docker-compose.hub.yml

Generate the secret key

Do this once only: the command writes the key to a .env file, which Docker reads on every start.

echo "LINKR_SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')" > .env

$b = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b)
"LINKR_SECRET_KEY=$([Convert]::ToBase64String($b))" | Out-File -Encoding ascii .env

Start Linkr

The first start downloads the images (around 780 MB).

docker compose -f docker-compose.hub.yml up

Open Linkr

Go to http://localhost:3000 and follow the setup wizard: it has you create the administrator account and offers to install demo data.

You're set

Linkr is running. The sections below are there when you need them: what the wizard does, where your data lives, how to change version.

The first-launch wizard

The very first visit shows not the login page but a three-step wizard — there is no user yet. Subsequent visits show the usual login page.

Database

The wizard shows the database the server is using. This screen is read-only: the database is configured server-side through LINKR_DATABASE_URL, and created automatically. To change it, edit the server configuration and restart.

Create Admin Account

This will be the instance's first administrator account. Enter a username and a password. In a development build the fields are pre-filled with admin / admin; a production build starts with empty fields.

Default data

Last step: install the demo workspace, which holds an OMOP database, concept mappings, an ETL pipeline and example projects. Click « Install and finish », or « Start empty » to begin with a blank instance. The choice is not final: content can be installed or removed later from the Catalog page.

Creating the administrator from the command line

For a scripted install, the wizard can be bypassed by calling the API directly:

curl localhost:8000/api/v1/setup/status

curl -X POST localhost:8000/api/v1/setup/initialize \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"a-strong-password"}'

The first command answers {"needs_setup": true} as long as the instance is not initialised.

Stopping and restarting

Started as above, Linkr holds the terminal: Ctrl+C stops it. To run it in the background, add -d, then stop it with down:

docker compose -f docker-compose.hub.yml up -d
docker compose -f docker-compose.hub.yml down

Stopping does not touch your data: it lives outside the containers.

The secret key

It signs login tokens and encrypts the passwords of the databases you register in Linkr. The server refuses to start without it.

Keep it stable: changing it logs everyone out and makes already-registered passwords unreadable. Do not share the .env file, and keep it with the Compose file: if you move Linkr or change machines, those two files plus the data folder are what you take with you.

Where your data lives

By default, everything you create is kept in a Docker named volume called linkr-data. It survives restarts, docker compose down and updates — but it belongs to Docker: you cannot open it in a file browser or copy it with your usual tools.

As soon as the data matters — several users, a server, anything you need to back up — mount a real folder instead. In docker-compose.hub.yml, replace the volume line with a path of your own:

    volumes:
      - ./linkr-data:/root/.linkr     # next to the Compose file
      # - /srv/linkr:/root/.linkr     # or a server path

Docker creates the folder if it does not exist. You will find the database and all the files there, backed up by a plain copy.

down -v deletes a volume, never a folder

docker compose down -v deletes the named volume, and with it all your data. A mounted folder is never touched by that command — one more reason to prefer a real path as soon as the content matters.

Changing version

The downloaded file names an exact version: your instance only changes when you decide it does. Both image: lines carry that number, and Linkr shows it in its status bar.

To move to a newer release, replace the number on both lines — published versions are listed on Docker Hub — then restart:

docker compose -f docker-compose.hub.yml pull
docker compose -f docker-compose.hub.yml up -d

Your data stays where it is, and database migrations are applied automatically on restart.

The two images move together

Frontend and backend stamp the same format version into exported data: a mismatched pair produces inconsistent exports. Both lines must always carry the same number.

Troubleshooting

Docker Compose refuses to start on LINKR_SECRET_KEY. The .env file is missing, empty, or not in the same folder as docker-compose.hub.yml. Redo step 2 from that folder.

python3: command not found in step 2. Python is only used to generate the key: openssl rand -base64 48 produces an equally valid value. Write it into .env as LINKR_SECRET_KEY=the-value.

Port 3000 is busy. Close the program that holds it (lsof -i :3000 on macOS/Linux finds it), or change the port in docker-compose.hub.yml: the first number of the "3000:80" line. Then carry the new address over to LINKR_CORS_ORIGINS, in the same file.

Slow, or refusing to start, on an Apple Silicon Mac. The images are built for the amd64 architecture; Docker runs them under emulation, more slowly. If it refuses to start a container, add platform: linux/amd64 under each service. For day-to-day use on such a machine, the manual install stays more comfortable.

The data disappeared after a down -v. That command deletes the named volume, with no recovery. Mount a real folder so it cannot happen again — see “Where your data lives”.

Next steps

Deploy on a server, with a real domain name and HTTPS: Production install.
Build your first project: Your first project.