Watching away from home

At home, Collectoh serves everything, from the app itself to every stream, on one port of your server: 8080 unless you change it with PORT, in plain HTTP. Away from home is free, and the easiest way there is direct access: switch it on and the server sets itself up. If nothing outside can reach your server at all, Collectoh Relay can.

#Choosing a route

Port forwarding on your router sends traffic that arrives on a port to one machine in your home. Direct access asks the router to do that for its own HTTPS port; a reverse proxy is a small web server of yours that accepts HTTPS and passes each request on to Collectoh.

#Direct access

Your server answers from anywhere at an address of its own, such as https://6c3e2a51-….direct.collectoh.com:32443, over HTTPS. It's free.

1. Sign your server in to your Collectoh account, under Admin → Settings → Collectoh account. Setup asks for this first.
2. In Admin → Remote access, switch on Let people reach this server from outside, directly. Setup offers it as its last step, already on.
3. After a minute or two, the page says it's ready and shows your server's address. Open it on a phone using mobile data to try it.

What happens on the way:

• A name. collectoh.com gives your server a name of its own.
• A certificate. Your server gets a certificate for that name from Let's Encrypt, with a key that never leaves it. Everything between a viewer's device and your server is encrypted.
• Its own port. Your server listens on its HTTPS port, 32443 unless you change it with HTTPS_PORT.
• The router. Your server asks your router to forward that port to it, over UPnP or NAT-PMP, which most routers have on. If yours says no, or doesn't answer, the page says so, and what to open yourself. Some routers say yes and never do it; if the router says yes and nothing gets through, the page says so, shows what to open yourself, and points at your computer's firewall too.
• A look from outside. collectoh.com connects to your server the way a phone on mobile data would. Only once it gets through does the name lead to your home, and the address appear on the page. It looks again every few hours, so the name follows your home's address when your provider changes it.
• Over IPv6 too. If your internet has IPv6, your computer has an address of its own on the internet, with no router's port in between. collectoh.com looks there as well, and once it gets through, the name leads there too. That reaches many homes no forwarded port can, such as those whose provider shares one IPv4 address between many homes. If only IPv6 got through, the page says so: visitors whose own internet has IPv6, as most phone networks do, get in, and the rest need the port opened or the relay.

When PUBLIC_URL isn't set, invitation and password-reset links use the direct address. Collectoh's apps try your server's addresses at home first, then the direct address, and the relay last.

Router settings, on the same page, let you open the port yourself instead (Open the port on the router automatically, off), or ask the router for another port when 32443 is taken there (Port on the router). Check again asks collectoh.com to look now. Switching direct access off takes the port back from the router at once.

#Open a port

When your router won't open the port for your server, you open it once yourself. Admin → Remote access shows exactly what to forward, for example: Forward TCP port 32443 to 192.168.1.20, port 32443.

1. Open your router's settings page. It's usually at http://192.168.1.1 or http://192.168.0.1, printed on a label on the router with the password. Mesh systems (Google Nest Wifi, Eero, Orbi, Deco) use their phone app.
2. Find Port forwarding. Routers also call it Virtual servers, NAT forwarding, Applications & Gaming or Port mapping; on a mesh app it's usually under Advanced or Network settings. On Zyxel-made routers, such as CenturyLink's, it's in the menu behind ☰ at the top right: Network Setting → NAT → Port Forwarding → Add New Rule, with the same port in all four port boxes.
3. Add a rule: protocol TCP, outside port 32443 (or the port the page shows), to your server's address, port 32443.
4. Save, then press Check again in Admin → Remote access.

A few things make it last:

• Keep your server's address. Routers hand out addresses at home as devices come and go. Give your server a fixed one in the router's DHCP or Address reservation settings, so the rule keeps pointing at it.
• Only that port. It speaks nothing but HTTPS, with your server's own certificate. Never forward 8080.
• Or switch UPnP on. If your router has UPnP or NAT-PMP switched off, switching it on lets your server open and close its port itself.
• In Docker, on its own network, your server can't see the router to ask it. Publish the port (the compose file does: ${HTTPS_PORT:-32443}) and forward it yourself, or run the container on the host's network (network_mode: host) so it can ask.
• A VPN on the server's computer. Visitors still come in through the router's port; the page says when your server's traffic goes out through a VPN, and collectoh.com asks your router for your home's address. If your router can't say, leave Collectoh out of the VPN with its split tunnelling.
• Your computer's firewall. The router can forward the port and the connection still stop at the computer Collectoh runs on. Allow incoming connections on TCP port 32443 there, on the network your server is on, which at home is usually a private one. On Windows, open Windows Defender Firewall → Advanced settings → Inbound Rules → New Rule… and make a Port rule for TCP 32443. On Linux with ufw, run sudo ufw allow 32443/tcp.
• Over IPv6. Most routers stop incoming IPv6 connections until you allow them. If the page says nothing answered over IPv6, find your router's IPv6 firewall settings (some call a rule there a pinhole, or put it beside port forwarding) and allow incoming TCP port 32443 to your server. Your computer's own firewall rule, above, covers IPv6 too. Over IPv6 visitors come straight to your server's own port, so this works only while Port on the router is left empty.
• When nothing gets through. If the page says your server reaches the internet through an address others can't reach back, your provider shares one address between many homes (carrier-grade NAT), or another router sits in front of yours. No port you open can help over IPv4. If your internet has IPv6, direct access may still reach your server there (above); otherwise use Collectoh Relay or a VPN.

#Set PUBLIC_URL

PUBLIC_URL is your own address for your server, such as https://media.example.com, when you reach it through a reverse proxy or a VPN. With direct access you don't need it: unset, Collectoh uses the direct address. Collectoh uses PUBLIC_URL in:

• invitation links and password-reset links
• sign-in through outside providers
• notifications
• Chromecast streams
• the connection test on the Diagnostics page

Set it in .env, then run docker compose up -d:

PUBLIC_URL=https://media.example.com

#Using a VPN

Install Tailscale, or your own WireGuard setup, on the server and on each device. Then open Collectoh at the server's VPN address, on port 8080. Nothing is exposed to the internet and the traffic is encrypted. A VPN also works when your internet provider shares one public address between many homes (carrier-grade NAT).

#Using a reverse proxy with HTTPS

1. Point a domain name, such as media.example.com, at your home's public IP address.
2. On your router, forward TCP ports 80 and 443 to the machine running the proxy.
3. Run Caddy or nginx, as shown below.
4. Set PUBLIC_URL to the https:// address.
5. Set TRUSTED_PROXY, as described below.

#Caddy

Caddy gets and renews a Let's Encrypt certificate by itself. To run it alongside Collectoh, save this as docker-compose.proxy.yml next to docker-compose.yml:

services:
  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
    depends_on: [server]
volumes: { caddy-data: }

Then save this as Caddyfile in the same folder:

media.example.com {
    encode zstd gzip
    respond /dlna/* 404            # DLNA is for the home network, never through the proxy
    reverse_proxy server:8080 {
        flush_interval -1          # required: do not buffer SSE or HLS
    }
    request_body { max_size 2GB }  # artwork/subtitle uploads
}

Start both with:

docker compose -f docker-compose.yml -f docker-compose.proxy.yml up -d

The flush_interval -1 line is essential. Without it, Caddy holds responses back, and live updates and streams break in ways that look like faults in Collectoh.

#nginx

nginx needs the same things: HTTPS, no response buffering, room for uploads, and the visitor's real address passed on to Collectoh. This example uses a certificate from a tool such as certbot:

server {
    listen 443 ssl;
    server_name media.example.com;

    ssl_certificate     /etc/letsencrypt/live/media.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/media.example.com/privkey.pem;

    client_max_body_size 2g;          # artwork, subtitle and photo uploads

    location /dlna/ {
        return 404;                   # DLNA is for the home network only
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;          # required: do not buffer live updates or streams
    }
}

If Collectoh runs on a different machine from nginx, change 127.0.0.1:8080 to that machine's address.

#Telling Collectoh about the proxy

When you use a proxy, every request reaches Collectoh from the proxy's address. TRUSTED_PROXY tells Collectoh which address that is, so it can trust the visitor's real address that the proxy passes on.

Without TRUSTED_PROXY, everyone who arrives through the proxy looks as if they're on your home network. Remote bandwidth caps then don't apply. Worse, if the proxy's address is inside a trusted network (see below), visitors from the internet are signed in as that network's account.

Add it to the server's environment: section in docker-compose.yml. You can list more than one range, separated by commas:

services:
  server:
    environment:
      TRUSTED_PROXY: 192.168.1.20/32

Which address to use:

• Proxy on another machine: that machine's address, as in the example above.
• Proxy on the same machine, with Collectoh installed without Docker: 127.0.0.1/32.
• Collectoh in Docker: the subnet of its Docker network. Run docker network inspect collectoh_default to find it.

Name only the proxy, never your whole home network. A device at a trusted address can tell Collectoh it is anyone. DLNA also refuses requests from these addresses.

#Collectoh Relay

Your server can be reached from anywhere through a relay of ours, with nothing to set up on your router: free, at a quality fine for a phone, and in HD with Plus. It's for a server direct access and the other routes above can't reach, for example when your internet provider shares one public address between many homes (carrier-grade NAT).

1. Sign your server in to your Collectoh account, under Admin → Settings → Collectoh account.
2. In Admin → Remote access, switch on Reach this server through Collectoh Relay.
3. After a minute, the page says it's ready and shows your server's address, such as https://6c3e2a51-….relay.collectoh.com. Open it on a phone using mobile data to try it.

Your server keeps a connection open to the relay, and gets a certificate for its address itself. What passes is encrypted from each viewer's device to your server, so the relay passes on what it can't read. Collectoh's apps try your server's own addresses first, at home, at its direct address and at PUBLIC_URL, and use the relay only when those don't answer.

• What it carries. Without Plus, the relay carries your server at about 2 Mbps, shared by everything passing through it, and up to 100 GB a month; the page shows both. With Plus, it carries HD, up to 1 TB a month, about seven hours of HD a day. A film over what the relay carries is converted to a lower quality instead of being refused. When a month's amount is used, the relay pauses for your server until the next month; everything else carries on.
• Invitations. When PUBLIC_URL isn't set, invitation and password-reset links use the relay address, so the people you invite can reach you too.
• Always away. Everyone who comes through the relay counts as away from home, even with Treat the internet-facing address as local on, so a trusted network never signs them in and your limits for streams from away apply.
• Switching it off closes the connection to the relay at once.

#Checking it works

Go to Admin → Remote access. Direct access shows how far it got, what your router did, and what collectoh.com found when it last looked from outside, with Check again. Above it, the page shows:

• your PUBLIC_URL, and whether Collectoh answered there the last time it was tested. Test now tests it again. If the address is a private one that only works at home, the page says so.
• whether the address uses HTTPS.
• whether TRUSTED_PROXY is set. If your address is https:// but TRUSTED_PROXY isn't set, the page warns you, because everyone arriving through the proxy then looks as if they're at home.
• the addresses devices at home use.
• how many people are streaming from away right now, and roughly how much they're sending together.

The test runs from the server itself. Some routers answer it even when nothing outside can reach the server, so also try the address on a phone using mobile data. Admin → Diagnostics shows the same test.

#Home or away

Collectoh treats each session as either local or remote. Bandwidth caps, and HEVC for remote streams, only apply to remote sessions. These settings are in Admin → Settings → Network:

• Local networks: the address ranges that count as home, one per line, such as 192.168.1.0/24. Collectoh detects them from the server's own network the first time it starts. In Docker, it may only detect the container's network, so check that your home network's range is listed.
• Treat the internet-facing address as local: for homes behind double NAT or carrier-grade NAT, where even the public address is really your home. Every session then counts as local, including people who really are away, so bandwidth caps never apply. People coming through Collectoh Relay still count as away.
• Trusted networks: a device in one of these ranges is signed in as a chosen account without a password, for example the television in your living room. You can only choose regular accounts, never an admin. If ranges overlap, the most specific one wins. Keep each rule to a single device, such as 192.168.1.50/32, because anything that can use that address gets that account.

#Quality away from home

Admin → Remote access has rules for every stream from away, whoever is watching:

• Limit each stream: the most one stream from away is sent. A film over the limit is converted to a lower quality instead of being refused.
• Internet upload speed (Mb/s): what your connection can send, from a speed test. Streams from away share it: a new one gets what the others leave, and never less than 750 kb/s. Leave it empty if you don't want streams to share.
• Streams per person away from home: how many streams one account can watch at once from away. Streams at home don't count.
• Require HTTPS from away: plain HTTP from the internet is refused, so a password never crosses the internet unencrypted. Devices at home, on a VPN, or arriving through a proxy named in TRUSTED_PROXY that used HTTPS are not affected. You can't turn it on while you're connected from away over plain HTTP, because that would cut you off.

Each account in Admin → People also has these settings. Where an account's limit and the server's differ, the lower one applies:

• Remote bandwidth cap (kbps): applies only away from home. A stream above the cap is converted to a lower quality instead of being refused.
• May transcode: when this is off, the account can only play what needs no conversion.
• Streams at once: how many streams the account can play at the same time.

The player also measures each connection and sizes conversions to suit it. If your server has a hardware HEVC encoder, remote streams use HEVC, which gives a sharper picture over the same connection. See playback and transcoding.

#Playing on other screens

#On another Collectoh

Any Collectoh that's open and signed in, such as in a television's browser or on another computer, can play what you send to it. The Play on button in the header lists your own devices wherever they are, plus other household members' devices when you're at home.

Pick a device and whatever you're watching continues there from the same moment. The bottom of your screen becomes a remote control for it. The receiving device plays under its own account. You can rename each device from the same list. Let other devices play on this one turns off receiving on the device you're using.

#On a Chromecast

In Chrome and other browsers built on Chromium, a Cast button appears in the player once a Chromecast is found on your network. Casting sends the film to the Chromecast from where you are and pauses it in the browser. The browser keeps reporting progress, so the film stays in Continue Watching.

The Chromecast fetches the stream from your server at PUBLIC_URL, so the Chromecast must be able to reach that address.

#Watch Together

Watch together on a film, episode or video opens a room that plays it for everyone in the room at the same time.

• Copy the invite link from the room's panel. Send it to people who have accounts on your server and can see that title.
• Play, pause and seek are shared. The room waits for anyone who is still buffering, and keeps everyone within about half a second of each other.
• The panel shows who is there and whether they're ready, and has a chat.
• If someone's connection drops, the room stops waiting for them after 15 seconds and removes them after two minutes.

#Keeping accounts safe

#Two-factor sign-in

Each person can add a code from their phone to their sign-in, under Settings → Two-factor authentication:

1. Press Set up two-factor authentication.
2. On your phone, tap Open in an authenticator app, or type the secret shown into your authenticator app.
3. Enter the six digits the app shows, then press Turn it on.
4. Keep the recovery codes somewhere safe. Each code works once, and they're your way back in if you lose your phone.

Require two-factor authentication of administrators, in Admin → Settings → Security, makes two-factor sign-in compulsory for admins. Until they set it up, they can sign in and watch but can't do any admin tasks. Set up your own first, because turning the rule off again is also an admin task.

#Sessions and devices

• Everyone can see where their own account is signed in, under Settings → Signed-in devices: each device's name, what it is, when it was last seen and from which address, with a Sign out button. Use it for a lost phone or a television you've given away.
• In Admin → People, open an account. Devices lists everywhere it's signed in, each with a Sign out button.
• Changing a password signs that account out everywhere.
• Taking away someone's access to a library signs them out and stops anything they're watching.
• Admin → Sessions shows who is watching what, and whether they're away from home. End stops a stream, with an optional message.
• Repeated failed sign-ins are slowed down, and an account that keeps failing is locked for a while.

#Checklist

• Use direct access, a VPN, or HTTPS through a reverse proxy. Never expose port 8080 itself to the internet.
• Set TRUSTED_PROXY to the proxy's address only.
• Keep each trusted network rule to a single device.
• Turn on two-factor authentication, and require it for admins.
• Give each person their own account. If your upload speed is limited, enter it in Admin → Remote access so streams from away share it.
• Turn on Require HTTPS from away once your proxy works.
• Keep DLNA on your home network. Both proxy examples above already block it. See DLNA.