Install and first setup
This is everything, in order, with what you will see at each point.
You need one machine running Ubuntu that stays on, and about twenty minutes. Most of
that is the server building itself while you wait.
What you will be asked for
Once: **an address.** The installer offers two kinds, and either one works from
anywhere.
**One GeekStream gives you.** Pick something short — your own name, your family name,
anything — and your server's address becomes `thatname.geekstreammedia.net`. Nothing to
set up, and it stays yours. If you have no opinion about this, press return.
**A domain you already own.** Your address, on your account, not ours. It needs one
thing done first, described below.
That is the only question the installer asks.
### Bringing your own domain
Your server never opens a port on your router. It dials out to Cloudflare through a
tunnel, and your address points at that tunnel — which is why GeekStream works behind
any router with nothing forwarded, and why nothing about your setup is guessable from
outside.
Only whoever controls a domain can create a tunnel on it. GeekStream's address service
makes them for `geekstreammedia.net` and cannot make one anywhere else. That is why
bringing your own domain means bringing a tunnel token with it, and it is also the
reason GeekStream never asks for a key to your domain: a key that could create the
tunnel for you could equally rewrite all of your DNS.
Your domain has to be on Cloudflare. Adding it there is free.
At one.dash.cloudflare.com, under **Networks >
Tunnels**:
1. Create a tunnel. Any name will do. Choose the **Docker** option.
2. It shows you a long command. Copy the token out of it — the part after `--token`,
and nothing else on that line. Pasting the whole command is fine; the installer
takes the token out of it.
3. Open the tunnel's **Public Hostname** tab and add:
| | |
|---|---|
| Subdomain and domain | your address, for example `media.yourname.com` |
| Type | HTTP |
| URL | `client-gateway:8780` |
That URL is not a typo and not an address on your network. It is the name your tunnel
uses to reach GeekStream once both are running on your machine. A tunnel pointed
anywhere else answers `502` forever.
Then run the installer, choose option 2, and paste the address and the token. It checks
the name exists before it writes anything, and tests the finished address from outside
before it says it is done — so if something in the Cloudflare setup is wrong, you find
out during the install rather than a week later, and it tells you which part.
Running the installer again later leaves your own domain alone. There is nothing of
ours behind it to renew.
It never asks for your Usenet password, your indexer keys, or any other credential.
Those are entered later, in the dashboard, on a page only you can reach.
Before you start
**On a machine at home:** nothing to prepare.
**On a rented server** (Oracle Cloud, AWS, anything similar): your provider has its own
firewall, outside the machine, which no installer can open. Allow inbound **TCP 8790**
for this machine before you begin, or your television will not be able to play anything.
On Oracle Cloud that is: **Networking → Virtual Cloud Networks →** your VCN **→ Security
Lists →** Default Security List **→ Add Ingress Rules**, source `0.0.0.0/0`, protocol
TCP, destination port `8790`.
Installing
sudo bash installer/linux/install.sh
Run it twice, or twenty times; it checks before it acts and leaves alone anything you
already have. If it stops, it says which step stopped and gathers a report you can send
as it stands — there is nothing secret in it.
What it does, in order:
1. **Checks this machine.** Ubuntu, 64-bit Intel/AMD or ARM, memory, and free space. It
warns rather than refuses when a machine is small.
2. **Checks what is already here.** If something else is using a port GeekStream needs,
it stops and names what is holding it, rather than fighting it. If Plex, Jellyfin,
Sonarr or similar are running, it says so and leaves them alone — GeekStream runs its
own copies and will not touch yours.
3. **Installs Docker**, if it is not here already, from Docker's own repository.
4. **Places the server files** and records which version they are.
5. **Creates your keys.** The one that encrypts your library is generated here and never
leaves this machine. Keep it: without it, nothing already saved can be read again.
6. **Asks for your address** — one it gives you, or one you already own. This is the
one question.
7. **Builds the server** for this machine's processor. A few minutes; longer on a small
machine.
8. **Checks before starting**: that every engine is built for this processor, that each
can read the files it is given, and that the port your television streams over is
open.
9. **Starts all nine services** and waits for each to be genuinely ready.
10. **Waits for your address to answer**, fetched from outside like a television
would. The install is not finished until it does. On your own domain, a reply
that is not the right one names the setting to change.
Then it prints your address and saves everything it told you to
`/etc/geekstream/your-geekstream.txt`, with a copy in your home directory. You do not
need to write any of it down.
sudo bash installer/linux/install.sh --details
shows that page again at any time.
First setup, in the dashboard
Open your address in a browser. Any computer, phone or tablet, anywhere — it does not
have to be on the same network as the server.
1. **Create your owner account.** Your password protects everything on this server, so
make it a good one; twelve characters at least. Wrong guesses get slower on purpose,
so nobody can work through a list of passwords.
2. **Enter your Usenet provider, once.** InfiniDysk, AIOStreams and NZBGet are all
configured from that one entry, each given its own share of your account's
connections. You never type it three times.
3. **Enter your indexers.** Same idea: saved once, used by everything.
4. **Choose your quality.** Whatever you pick here is sent to the streaming engine, so it
stops offering what your server would only throw away.
5. **Pair your television.** Create a code in the dashboard, type it on the television,
and approve the device when it appears. The code works from anywhere.
Then, back on the server:
sudo bash installer/linux/install.sh --activate-route
This registers the route your television plays through. It is separate because it plays
a real file to prove the route works, which needs a provider and an indexer saved first.
If something is not right
Every screen has its own check — a **Check again** button that tells you what is wrong
with *that* screen, rather than sending you somewhere else to find out.
sudo bash installer/linux/install.sh --troubleshoot
gathers everything at once. Nothing in that report is a credential; send it as it stands.
See [Troubleshooting](troubleshooting.md) for what the specific messages mean.