ServiceFloGuide

Install ServiceFlo

This page takes you from nothing to a ServiceFlo site you can sign in to. It has two parts:

  1. A trial on your own computer. About fifteen minutes, most of it waiting.
  2. A real install, on a server other people can reach. The same steps, plus a host name, HTTPS and email.

Do the trial first, even if you plan a real install. It shows that everything works before a host name and certificates are involved.

What you need

  • A computer or server with Docker (Docker Desktop on Windows or macOS, Docker Engine with the Compose plugin on Linux). Docker runs each part of ServiceFlo in its own container, a small sealed box with everything that part needs.
  • git and make. Linux and macOS usually have both; on Windows, use WSL (the Linux environment built into Windows).
  • About 4 GB of memory and 10 GB of disk free for a trial. A real install for a mid-sized organisation is comfortable with 2 CPUs and 8 GB.
  • Internet access during the first start: Docker downloads and builds what it needs.

You do not need Python, a database or a web server installed: they are in the containers.

Part 1: a trial on your own computer

1. Get the code

git clone https://github.com/serviceflo-io/serviceflo-itsm.git serviceflo
cd serviceflo

This gets the newest code. To install a named release instead, check out its tag (the releases are listed in CHANGELOG.md):

git checkout v0.1.0a1

2. Make your settings file

ServiceFlo reads its settings from a file called .env in this folder. Start from the example:

cp .env.prod.example .env

Open .env in a text editor. Three settings near the top are empty: they are secrets only your install knows. Run each of these commands and paste what it prints after the matching = (no spaces, no quotes):

Setting Command that makes a value
DJANGO_SECRET_KEY openssl rand -hex 32
FIELD_ENCRYPTION_KEYS openssl rand -base64 32 | tr '+/' '-_'
POSTGRES_PASSWORD openssl rand -hex 24

The finished lines look like this (with your own values):

DJANGO_SECRET_KEY=3f9c0a…
FIELD_ENCRYPTION_KEYS=Zk1uQ0…=
POSTGRES_PASSWORD=8b1d2e…

Leave the rest of the file as it is for the trial: it is already set for http://localhost:8000.

Keep a copy of .env somewhere safe. FIELD_ENCRYPTION_KEYS locks the passwords ServiceFlo stores for you (for mailboxes, for example). If it is lost, they cannot be read again, even from a perfect backup.

Do not change POSTGRES_PASSWORD after the first start. The database remembers the password it was created with.

3. Start it

make prod-up

The first start takes several minutes: Docker builds two images (the application and the database) and then creates the database. Later starts take seconds.

Check that it is up:

docker compose -f docker-compose.prod.yml ps

Six services are listed. web should say healthy after a minute or so; while it says starting, it is still preparing the database.

Service Its job
web The site itself, on port 8000.
worker Background jobs, such as sending email.
timers Jobs that run on a clock, such as checking service targets.
mail Fetches email from the mailboxes you connect.
postgres The database: every ticket, guide and setting.
redis A short-term store that keeps the site fast and remembers who is signed in.

4. Make your account

docker compose -f docker-compose.prod.yml run --rm web createsuperuser

It asks for a username, an email address and a password. This first account is a superuser: it can see and change everything, including the settings of the install itself.

5. Sign in

Open http://localhost:8000/ and choose Sign in. You land on an empty site: no workspaces, teams or tickets yet.

Open Settings in the menu and choose Create a workspace. A workspace is one group’s service desk (IT Support, for example). Give it a name and it is ready to use: you are its admin, it has a first team and queue, and the statuses and priorities a ticket needs are in place. (Skip this if you are about to load the demo in step 6, which brings its own.)

6. Optional: fill it with a demo

To see ServiceFlo with data in it, build the demo: a made-up university with about 600 tickets, a knowledge base, a service catalog, changes and assets. It takes about four minutes.

docker compose -f docker-compose.prod.yml run --rm web seed_demo --force

Then sign in as the demo agent mchen with the password serviceflo.

The demo is for looking around, not for building on: every demo agent has that same well-known password. For a real install, start again with an empty database (see “Starting again” below) and do not run this command.

Stopping and starting

docker compose -f docker-compose.prod.yml stop     # stop; nothing is lost
make prod-up                                       # start again

Starting again

To throw the trial away, data and all:

docker compose -f docker-compose.prod.yml down -v

The -v deletes the volumes, which is where Docker keeps the database and the uploaded files. Never use -v on an install whose data you want. Without -v, down is safe.

Part 2: a real install

A real install is the trial plus four things. Do them on the server that will run ServiceFlo, after steps 1 and 2 above.

1. A host name

Choose the name people will type, for example help.example.org, and point it at the server in DNS. Then set it in .env:

DJANGO_ALLOWED_HOSTS=help.example.org
DJANGO_CSRF_TRUSTED_ORIGINS=https://help.example.org
SITE_BASE_URL=https://help.example.org
WAGTAILADMIN_BASE_URL=https://help.example.org

2. HTTPS

Delete these two lines from .env. They are only for a trial over plain http://:

DJANGO_SECURE_SSL_REDIRECT=false
DJANGO_SECURE_COOKIES=false

ServiceFlo itself listens only on the server’s own address (127.0.0.1:8000), where nobody outside can reach it. A reverse proxy stands in front: a small web server that holds the HTTPS certificate, takes the requests from the internet and passes them on. Caddy is the simplest, because it gets and renews the certificate by itself. Its whole configuration (the Caddyfile) is:

help.example.org {
    reverse_proxy 127.0.0.1:8000
}

If you use nginx or a load balancer instead, two things matter: it must send the X-Forwarded-Proto header (that is how ServiceFlo knows the request came over HTTPS), and it must allow uploads of at least 25 MB.

3. Email

Without this, ServiceFlo sends nothing: notifications are only written to the logs. Set the mail server ServiceFlo sends through, and the address its mail comes from:

EMAIL_URL=smtp+tls://user:password@smtp.example.org:587
DJANGO_DEFAULT_FROM_EMAIL=helpdesk@example.org

Receiving email (so that a message becomes a ticket) is set up later, inside ServiceFlo, under Settings.

4. Your people

DIRECTORY_PROVIDER=none means accounts are made by hand inside ServiceFlo. To fill them in from Active Directory or LDAP instead, see directory.md. With a directory connected, LDAP_AUTH_ENABLED=true also lets people sign in with their directory username and password.

Better still, where your organisation has one, is single sign-on: people sign in on your organisation’s own page and no password reaches ServiceFlo. See Single sign-on.

Then start it and make your account, as in the trial:

make prod-up
docker compose -f docker-compose.prod.yml run --rm web createsuperuser

Open https://help.example.org/ and sign in.

Before you call it done

  • .env is copied somewhere safe, off the server.
  • A backup runs every night and is copied off the server: Backups and upgrades.
  • You have put a backup back once, on a spare machine, to know that it works.
  • An uptime monitor watches https://help.example.org/api/v1/health.

If something goes wrong

Look at the logs first. They usually say what is wrong in plain words:

docker compose -f docker-compose.prod.yml logs --tail 50 web
What you see Likely cause
set POSTGRES_PASSWORD in .env when starting That line in .env is empty, or .env is not in this folder.
web never becomes healthy Read its log. A missing or misspelt setting is named there.
“Bad Request (400)” on every page The name in the address bar is not in DJANGO_ALLOWED_HOSTS.
An error about CSRF when you sign in DJANGO_CSRF_TRUSTED_ORIGINS does not match the address, including http:// or https://.
You sign in and are sent straight back to the sign-in page Plain http:// without the two trial lines, or the proxy does not send X-Forwarded-Proto.
The password authentication for the database fails POSTGRES_PASSWORD was changed after the first start. Put the old one back.
No email arrives EMAIL_URL is not set, or the worker service is not running.

A longer list is at the end of deployment.md.

Next