Run SENAITE LIMS in under 5 minutes with Docker

The quickest way to look at SENAITE LIMS is the public Docker image. It contains the Python 2.7 interpreter, every system library and a complete SENAITE instance, so nothing has to be compiled on your machine. This guide takes you from an empty Docker installation to a SENAITE site in your browser.

What you need

• Docker Desktop (macOS, Windows) or Docker Engine (Linux). The image is published for linux/amd64 and linux/arm64, so it runs natively on Apple Silicon as well.
• A free port on localhost. The examples use 8080.
• About 500 MB of download.

Pick the right tag

The image is senaite/senaite on Docker Hub. Two kinds of tags matter:

There is no latest tag. The README of the senaite.docker repository still shows senaite/senaite:latest, and that command fails with a manifest error. Use 2.x to see what SENAITE does today, and a version tag when you need a demo that looks the same next month.

Start the container

docker run --rm --name senaite -p 8080:8080 senaite/senaite:2.x

• --rm removes the container, and the database inside it, when you stop it.
• -p 8080:8080 maps the container port to your machine. If 8080 is taken, use -p 8081:8080 and open port 8081 instead.

When the log shows a line ending in Ready to handle requests, the instance is up.

Create a SENAITE site

Open http://localhost:8080 and click Create a new SENAITE site. Log in with the user admin and the password admin. The form asks for three things:

• Path identifier: the id of the site in the database, and the first part of its URL. Use senaite.
• Title: shown in the browser tab.
• Default timezone: the laboratory’s timezone. It ends up in every date the system records.

Click Create SENAITE Site. After a short wait you land in an empty SENAITE at http://localhost:8080/senaite.

Keep your data

As long as --rm is on the command line, every stop throws the site away. Once you enter anything you want to see again, mount a directory for /data, where the image keeps the database, the attachments and the logs:

docker run -d --name senaite -p 8080:8080 \
  -v "$PWD/senaite-data:/data" senaite/senaite:2.x

The container can also create the site on its first start and set a different admin password:

docker run -d --name senaite -p 8080:8080 \
  -v "$PWD/senaite-data:/data" \
  -e SITE=senaite -e PASSWORD=choose-one \
  senaite/senaite:2.x

Setting SITE or PASSWORD makes the container run a buildout before the instance starts, so the first start takes noticeably longer and needs internet access. The generated configuration lives inside the container, not under /data. Changing these variables later has no effect until you recreate the container.

What you see, and what you do not

The new site is empty: no clients, no sample types, no analysis services. SENAITE looks thin until that setup exists, which is why first impressions tend to undersell it. Two ways to fill it:

1. Load the test dataset that ships with SENAITE. It creates clients, sample types, methods, instruments and analysis services in one step. See Provision SENAITE LIMS with demo data.
2. Create a handful of records yourself: one client, one sample type, two analysis services. Then register a sample, receive it, enter results, verify them and publish the report. That one sample shows you more of the workflow than an hour of clicking through menus.

Where this setup stops

The image’s own README advises against running these containers in production as they stand, for good reasons:

• The admin password is admin unless you set one.
• There is no TLS and no reverse proxy in front of the instance.
• One process serves every request. A report that takes thirty seconds to render occupies one of its threads for thirty seconds.
• Backups, database packing and monitoring are left to you.

For a server, follow the Ubuntu 24.04 install guide, or look at the SENAITE Enterprise VM, which ships the production setup we run ourselves.

After the five minutes

If SENAITE looks like a fit, the next step is usually our 3-day workshop. We preconfigure a system for your laboratory beforehand and work through it with your team during the three days, with your sample types, your analyses and your workflow instead of test data.

Questions while you try it out? Get in touch.