The installer, step by step

One command sets up everything. It takes ten to twenty minutes, most of it spent building

the server image, and it prints every step as it goes.

This page lists those steps in order, says what each one is doing, and tells you what to

do when one of them stops. **You do not need to read it before installing.** It is here

for when something does not look right and you want to know whether that matters.

---

Running it

From a terminal on your GeekStream machine:

```

sudo bash /opt/geekstream/installer/linux/install.sh

```

It is safe to run again. It is written to be re-run: it picks up where things already

exist and does not redo work that is done. If an install fails halfway, fix what it

complained about and run the same command again.

Answer its questions as they come. It will ask you to choose an address and to set an

owner password, and nothing else.

---

The steps

### 1 — Checking this machine

Reads how much memory, disk and how many processor cores you have, and prints them.

**If it warns about memory or disk**, it is a warning and not a refusal. Under 3 GB of

memory or under 40 GB free, it says so and carries on. A small machine works; it fills up

sooner and builds more slowly.

### 1b — Checking what is already installed

Looks for anything already using the ports GeekStream needs, and for other media servers

running on the same machine.

**If it names something**, decide which you want on this machine. Two things cannot share

one port. It tells you what is holding it.

### 2 — Docker

Installs Docker if it is not there. This is the longest step on a fresh machine after the

image build.

**If this fails**, it is almost always the system being out of date. Run

`sudo apt-get update && sudo apt-get upgrade -y`, reboot, and run the installer again.

### 3 — Server files

Puts the server under `/opt/geekstream` and records which version it is.

### 4 — Secrets

Generates the keys this server uses to encrypt what it stores. They live in

`/etc/geekstream/secrets`, readable only by root.

**These are not recoverable.** If you lose them, everything the server has saved —

accounts, pairings, your library index — cannot be read again. They are included in

GeekStream's own backups; see [Updates, backups, migration](updates-backups-migration.md).

### 5 — Media route certificate

Creates the certificate your television uses to talk to the server over your own network.

### 5b — Your GeekStream address

**The one decision that needs thought.** This is how your television and your browser

reach the server.

- **The built-in address** — GeekStream gives you a name that works from anywhere, with no

router changes, no port forwarding and nothing to renew. This is the right answer for

almost everyone, and the only workable one if your router will not forward a port.

- **Your own domain** — if you already run a domain through your own tunnel, keep it. The

installer recognises this and leaves it alone.

**If it says it could not reach the address service**, your address is unchanged and

nothing is broken. Check the machine has working internet (`ping -c3 1.1.1.1`) and run the

installer again.

### 6 — Settings

Writes the configuration the services start from. Nothing to do.

### 7 — Server image

Builds the server. **This is the slow step** — several minutes on a fast machine, longer

on a small VPS or an ARM board. It looks like nothing is happening. It is working.

### 7b — Media tools

Checks the tools that read media files are present and runnable.

### 8 — Starting

Starts the services: the manager, the workers, the client gateway, the downloader and the

streaming engine.

### 8a — Checking the engines match this machine

Confirms the pieces built for your processor are the ones that got installed. This catches

an x86 image on an ARM machine, which otherwise fails later in a confusing way.

### 8b — Checking each engine can read its own secrets

Each service is handed only the credentials it needs. This proves each one can actually

read what it was given, rather than discovering it at two in the morning when something

tries to run.

### 8c — Opening the media route

Makes the path your television uses to fetch media.

### 8d — Checking the downloader accepts its credential

Confirms the downloader is reachable and takes the credential the server generated for it.

---

When it finishes

It prints the address of your dashboard and asks you to set an **owner password**. Type

it twice. It is not shown as you type — that is normal, and the cursor does not move.

Then open the address it printed in a browser, sign in as the owner, and continue at

[Your account, and pairing a television](account-pairing.md).

---

When something goes wrong

**Read the step number it stopped on.** It prints `STEP` with a number and a short name,

and that tells you which of the sections above to look at.

**Run it again.** Genuinely — most failures are transient: a package mirror was busy, the

network blinked, the address service was slow. The installer is built to be re-run and

will not repeat work that succeeded.

**If it stops in the same place twice**, collect this and it will usually be obvious:

```

sudo docker ps -a

sudo docker compose -f /opt/geekstream/canonical-runtime/compose.runtime.yaml logs --tail 80

df -h /

```

The first shows which services exist and whether they are running. The second shows what

the failing one said. The third shows whether you have simply run out of disk, which

produces a remarkable variety of unrelated-looking errors.

**Specific failures** — certificate problems, an address that will not resolve, services

that start and immediately stop — are listed with their fixes in

[Troubleshooting](troubleshooting.md).

---

Uninstalling

The same script removes everything, including your data, if you ask it to. See

[Uninstall](uninstall.md) before you do, because the secrets from step 4 go with it.