Offset Align on Docker, step by step

Part 1Do you already have Docker?

1.1Open Command Prompt.

Press the Windows key, type cmd and press Enter.

1.2In Command Prompt, type this command and press Enter:

1.3Look at what it says.

If you see something like this, you have Docker. Skip to Part 3:

Docker version 29.7.2, build 1a2b3c4

If you see this, you do not have it yet. Go to Part 2:

'docker' is not recognized as an internal or external command

Part 2Installing Docker

Only if Part 1 said you do not have it.

2.1Open your web browser and go to:

2.2Click the Download for Windows button.

A file called something like Docker Desktop Installer.exe downloads. It is large, about 600 MB, so this takes a few minutes.

2.3When it finishes, double-click that file.

2.4A window appears with some tick boxes. Leave them as they are. Click OK.

2.5Wait. It installs for a few minutes and then says Installation succeeded. Click Close and restart if it offers.

Your computer may restart during the installation.

2.6After restarting, open Docker Desktop: press the Windows key, type Docker, press Enter.

2.7The first time, it shows a license agreement. Click Accept. It may ask you to sign in or create an account. You can skip that, look for Continue without signing in or just close the sign-in box.

2.8Wait for Docker to start. Its status is shown in the bottom-left corner of the Docker Desktop window, next to the whale icon.

• Starting: wait, it is not ready
• Running: ready. This is what you want

The first start can take two or three minutes.

2.9Leave Docker Desktop open. It must be running whenever you use the product. It starts by itself when you switch your computer on.

2.10Check the installation. Close Command Prompt and open a new one (the old one will not recognise Docker yet), then run:

You should now see a version number. If you do, Docker is installed.

Part 3Getting Offset Align

3.1Download this file from the release page:

It is small, about 6 KB. It contains the configuration Docker uses to download the product.

3.2Make a folder for it. In File Explorer, go to your C: drive and make a folder called Offset, and inside that one called Align.

So you end up with:

C:\Offset\Align

3.3Right-click the zip file you downloaded and choose Extract All. In the box that asks where to extract the files, enter C:\Offset\Align and click Extract.

3.4Open that folder. You should see exactly three files:

compose.yaml
env.example
README.txt

If you see a folder inside the folder instead, open it and move those three files up one level.

Part 4Your settings file

4.1Open Command Prompt again (Windows key, cmd, Enter).

4.2Change to your new folder. Type this and press Enter:

cd changes the folder Command Prompt is working in. The text at the left of the window changes to show the folder you are now in. It should end with Align>.

4.3Make your own copy of the settings file:

It says 1 file(s) copied.

Why copy it: env.example is the blank one we ship. .env is yours, with your settings in it. Keeping them separate means an update can never overwrite your settings.

4.4Open your copy in Notepad:

Lines that start with # are comments and have no effect.

4.5Scroll down until you find these two lines. They have nothing after the equals sign:

SESSION_SECRET=
FIELD_ENC_KEY=

These are two secret keys the product uses internally. They must be long and random, and should never be shared.

4.6Leave Notepad open. Go back to the Command Prompt window and type this, then press Enter:

The first time, this downloads a small helper. You will see some progress bars. Then it prints one long line of letters and numbers.

The value is 64 characters long and different every time. No example is shown here, because a copied example would not be secret.

4.7Copy that line: select it with your mouse and press Enter.

4.8Go to Notepad. Click right after SESSION_SECRET= and paste (Ctrl+V). The line now looks like:

SESSION_SECRET=<the long line you just copied>

4.9Now do it again for the second one. Go back to Command Prompt, press the Up arrow to bring back the same command, press Enter. It prints a different line. Copy that one, and paste it after FIELD_ENC_KEY=.

The two values must be different from each other.

4.10In Notepad, press Ctrl+S to save, then close Notepad.

Keep this file safe. If you lose those two values: everyone is signed out, and any password the product has stored cannot be read back. Back the file up somewhere, or at least do not delete the folder.

Part 5Choosing a port

Each program on your computer listens on its own port number, and only one program can use a port at a time. The product uses 8080 by default.

5.1Check whether anything is already using 8080. In Command Prompt:

If nothing is printed, port 8080 is free. Skip to Part 6.

If you see a line of numbers, something is already using it. Pick another number, 8081, 8082, 8090, anything up to 65535, and check that one the same way until you find a free one.

5.2If you had to change it, open your settings again:

Find these two lines and change the number in both. They must match:

HTTP_PORT=8080
PUBLIC_URL=http://localhost:8080

If you chose 8085, they become:

HTTP_PORT=8085
PUBLIC_URL=http://localhost:8085

Why both: the first is the port the product listens on. The second is the address the product writes into the emails it sends. If they differ, your colleagues get emails with links that go nowhere.

Save with Ctrl+S and close Notepad.

Part 6Starting it

6.1Make sure Docker Desktop is open and says Running at the bottom left.

6.2In Command Prompt, make sure you are still in your folder. The text at the left should end with Align>. If not:

6.3Type this and press Enter:

6.4Wait. The first time, this downloads the product, about 200 MB, so give it a few minutes on a normal connection. You will see lines of progress bars scrolling past.

6.5When it finishes you see three lines ending in Started, something like:

Container offset-align-app-1      Started
Container offset-align-worker-1   Started
Container offset-align-updater-1  Started

The product is now running.

What those three are: the first is the product itself. The second does the quiet jobs, reminder emails, nightly backups. The third installs updates later, when you ask it to.

Part 7Opening it

7.1Open your web browser.

7.2Go to:

(or whatever port you chose in Part 5)

7.3The first screen asks you to create the administrator account. Fill it in and submit.

Do this straight away. Until you do, anyone who can reach that address could create it instead of you.

7.4The installation is complete.

Part 8The five commands you will use

All of these must be typed in your folder, cd C:\Offset\Align first.

Is it running?

Stop it (your data is kept):

Start it again:

See what it is doing (press Ctrl+C to stop watching):

docker compose logs -f app

Danger. This one deletes everything, your accounts, your evidence, all of it, with no undo:

The difference is that -v on the end. Without it, your data is safe. With it, your data is gone. Do not type it unless you mean it.

Part 9Where your data is

Not in the folder you made. Docker keeps it in its own storage, called a volume, so that stopping and restarting never touches it.

You do not need to find it. To back it up, use Backups inside the product, Settings, then Backups, which writes a file you can copy anywhere.

Part 10Something went wrong

"'docker' is not recognized as an internal or external command"

Docker is not installed, or you opened Command Prompt before installing it. Close Command Prompt, open a new one, and try again. If it still says this, go back to Part 2.

"Cannot connect to the Docker daemon" or "Docker Desktop is not running"

Docker Desktop is not open, or has not finished starting. Open it from the Start menu and wait until the bottom left says Running.

"no configuration file provided: not found"

You are in the wrong folder. Command Prompt must be in the folder holding compose.yaml. Type:

and try again.

"port is already allocated" or "bind: address already in use"

Something else is using that port. Go back to Part 5 and pick another number, remembering to change both lines.

"pull access denied" or "repository does not exist"

Your .env is naming an image that cannot be reached. Open it and check these two lines are exactly as shipped:

OFFSET_IMAGE=ghcr.io/offsetsecurity/offset-align:latest
OFFSET_UPDATER_IMAGE=ghcr.io/offsetsecurity/offset-align-updater:latest

The page will not load in the browser

Check it is running with docker compose ps. All three should say Up. If one says Exited, look at why:

The product says it cannot start because a secret is missing

Part 4 did not save properly. Open notepad .env and check that both SESSION_SECRET= and FIELD_ENC_KEY= have a long line of letters and numbers after the equals sign, with no spaces.

Still stuck

Send us this, and we will tell you what it means:

That writes a file called logs.txt in your folder. Email it to info@offsetsecurity.net.

On Linux instead of Windows

The steps are the same. The differences:

• Install Docker with your package manager, or the script at https://get.docker.com
• cp env.example .env instead of copy env.example .env
• nano .env instead of notepad .env
• ss -ltn | grep 8080 instead of the netstat command

Everything else, the same commands, the same order.

Offset Security: info@offsetsecurity.net