Offset Aware 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 portal. 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 the portal's files

3.1Download the portal zip from the release page. Right-click it, choose Extract All and click Extract.

3.2In the extracted folder, open deploy\docker. It holds two files:

3.3Make a folder to run the portal from. In File Explorer, go to your C: drive, make a folder called Offset, and inside it one called Portal.

So you end up with:

C:\Offset\Portal

3.4Copy those two files into C:\Offset\Portal. That folder should now hold exactly:

compose.yaml
env.example

Part 4Your settings file

4.1Open Command Prompt (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 should now end with Portal>.

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:

Most of what you see is explanation, every line starting with # is a note to you and does nothing.

4.5Find this line. It has nothing after the equals sign:

This is a secret key the portal uses internally to keep people signed in. It must be long and random, and should never be shared.

4.6Leave Notepad open. In Command Prompt, type this and press Enter:

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

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

4.8In Notepad, click right after SESSION_SECRET= and paste (Ctrl+V).

4.9Now find these two lines and set the address your staff will use:

PORTAL_URL=https://localhost:3000
PORTAL_PORT=3000

PORTAL_PORT is the port the portal listens on. PORTAL_URL is the address that goes into the emails the portal sends your staff, so it has to be an address they can actually reach from their own computers, usually the server's name or IP, not localhost. For example:

If port 3000 is already in use on that machine, change the number in both lines to the same new number.

4.10Press Ctrl+S to save, then close Notepad.

Keep this file safe. Lose that secret and everyone is signed out.

Part 5Starting it

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

5.2In Command Prompt, make sure you are in your folder, the text at the left should end with Portal>. If not:

5.3Type this and press Enter:

5.4Wait. The first time this downloads the portal, a few hundred MB, so give it a few minutes.

5.5When it finishes you see lines ending in Started:

Container offset-aware-portal-1   Started
Container offset-aware-updater-1  Started

The portal is now running. The second container is the updater, which installs updates later when an administrator asks for one.

Part 6Opening it

6.1Open your web browser and go to:

Note https, not http. The portal always encrypts, even on your own network.

6.2Your browser shows a warning, "Your connection is not private", or similar.

This is expected. The portal makes its own certificate, and browsers only trust certificates bought from a company they recognize. Nothing is wrong.

Click Advanced, then Proceed to localhost (unsafe). The word unsafe is the browser being dramatic about a certificate it has not seen before.

6.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 the address could create it instead of you.

6.4The installation is complete.

Adding the course packs (Docker)

Offset Aware on Docker arrives with no courses. The ISO 27001, HIPAA and SAMA courses come as separate downloads, called course packs, because the videos are large and most organisations want only one or two.

The Windows installer downloads the packs you tick automatically. These steps are only needed for Docker.

1In the folder where you run Aware (the one holding compose.yaml and .env), make a new folder called packs.

2Download the packs you want from:

Save them into the packs folder. Do not unzip them.

3Open the .env file and add this as a new line at the end, then save:

Why: this keeps the courses with the rest of your data. Without it, the next update would remove them.

4Copy the packs in. Open a terminal in your Aware folder and run this as one line.

It prints nothing when it works, and takes a minute or so for the larger packs.

5Restart Aware so it reads the new setting:

6Sign in to Aware as the administrator, open Settings, and look at Training modules. The new courses are listed there.

To add another pack later, save it into the packs folder and repeat step 4. No restart is needed that time.

Part 7Setting it up for your staff

1. Settings, SMTP: point it at your mail server, so it can send invitations, reminders and password resets
2. Employees: import your staff from a spreadsheet, or add them one at a time
3. Send the invitations

Your staff open the same address from their own computers, sign in, work through the courses they've been given, take the quiz after each one, and upload any certificates they already hold.

Part 8The five commands you will use

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

Is it running?

Stop it (your data is kept):

Start it again:

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

docker compose logs -f portal

Danger. This one deletes every training record, 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 stopping and restarting never touches it.

It holds every training record, every uploaded certificate, and the administrator account. Copy it out before you move the portal to another machine.

Part 10Updating it

An administrator installs updates from inside the portal: Settings shows the installed version, checks for a newer one, and installs it with a button.

The updater container does the work. It downloads the new version, restarts the portal, and puts the old version back if the new one does not answer.

Nothing is downloaded or installed until somebody asks for it.

Part 11Something 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, try again. Still the same? 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 and wait until the bottom left says Running.

"no configuration file provided: not found"

You are in the wrong folder. Type:

and try again.

"port is already allocated"

Something else is using port 3000. Open notepad .env, change the number in both PORTAL_PORT and PORTAL_URL to the same new number, save, and run docker compose up -d again.

The browser says the page cannot be reached

Check it is running with docker compose ps. Both lines should say Up. Also check you typed https, not http.

Your staff cannot reach it from their computers

The address in PORTAL_URL has to be one they can reach, the server's name or IP, not localhost, which means "this computer" and is different on every machine. You may also need to open the port in the server's firewall.

Still stuck

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

That writes 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

Everything else, the same commands, the same order.

Offset Security: info@offsetsecurity.net