Five-minute quick start

PortLoom uses two Linux hosts that can run Docker: a public VPS with IPv4 and a NAS/internal server. The public VPS runs Server and the WebUI; the NAS runs only Agent and initiates the outbound connection.

0. Choose a hostname and open ports

Choose your own complete management hostname. An apex domain or any subdomain works, for example:

example.com          A  203.0.113.10
*.example.com        A  203.0.113.10   # optional, useful for future route names

There is no fixed naming rule and no portloom. prefix is required. Point the selected hostname to the VPS and allow public TCP 80, 443, and 2222. The NAS needs neither a public IP nor an inbound port.

ACME HTTP-01 requires public port 80 to reach Server's HTTP edge; with defaults, local VPS ports 80/443 must also be free. Open custom web/TCP ports and UDP route ports only when you create those routes.

1. Install Server on the VPS

Choose either path. Both run the same Server and managed-sshd images.

Option A: Compose template (inspectable configuration)

Open Install with the Compose template:

1. Download compose.yml and the environment template.
2. Rename the template to .env, then edit only the management hostname and administrator token.
3. Start it in a Compose UI or run docker compose up -d.

This is a conventional file-based Compose installation. The PortLoom installer script is not required first.

Option B: Secure installer (more automation)

The installer generates a random administrator token, resolves immutable images, verifies real HTTPS, and rolls back a failed activation:

curl -fsSLo install-server.sh https://docs.look4i.com/install-server.sh
less install-server.sh
chmod 0700 install-server.sh
DOMAIN='example.com' # replace with your complete management hostname
./install-server.sh --domain "$DOMAIN" --version 0.4.1

With either path, open https://your management hostname. The Compose path uses the administrator token in .env; the installer prints its generated token in the terminal.

2. Add an Agent in the WebUI

Sign in and open Add Agent:

1. Agent name: for example home-nas.
2. Server URL: the current https://your management hostname WebUI URL.
3. Public Server host: a public hostname or IPv4 address for the VPS.
4. SSH tunnel port: 2222 by default.
5. Select Generate command.

An unused installation command can be deleted/revoked from the token list. Already enrolled Agents are unaffected.

3. Run the generated command on the NAS

Paste the complete command generated by the WebUI on the NAS. The Agent installer checks Docker daemon access and Compose v2, accepts both docker compose and standalone docker-compose v2, and handles common Synology/QNAP PATH, hash-tool, and no-flock environments.

It creates an independent Ed25519 key, pins the Server SSH host key, enrolls with the one-time token, and removes the token from configuration after success. If installation fails, fix the reported prerequisite and rerun the same command to resume safely. Do not delete ~/.portloom/agent/data.

4. Create the first HTTPS route

Open Routes → Add route:

Field	Example
Name	Jellyfin
Client	home-nas
Protocol	HTTPS
Public domain	jellyfin.example.com
Path prefix	empty
Public port	empty (primary HTTPS edge)
Local host	127.0.0.1 or another NAS-reachable address
Local port	8096

If wildcard DNS is not configured, point jellyfin.example.com to the VPS separately. Save the route, wait for Local, Tunnel, and Public to converge, then open https://jellyfin.example.com.

5. Next steps

• Plaintext service: select HTTP.
• Sub-path: enter /jellyfin and enable Strip path prefix when required.
• Custom web port: enter a value such as 8443 and allow that TCP port.
• TCP/UDP: select the protocol and enter the required Public port.

See Docker installation for path differences, Route management for exact rules, and Backup, upgrade, rollback for operations.