Run the server

To try it on your own computer, Start the server and Sign in are enough.

For production, you need a host, a DNS name such as repo.example.com that points at it, and ports 80 and 443 open.

Start the server

Docker

Start the server.

docker run -d --name telesphorepo -p 127.0.0.1:8080:8080 -v telesphorepo-data:/data -v telesphorepo-backups:/backups ghcr.io/telesphorepo/telesphorepo:latest

Copy the admin password from the log.
Terminal window
```
docker logs telesphorepo
```

Docker Compose

Save this as compose.yaml in a folder of its own.

services:
  telesphorepo:
    image: ghcr.io/telesphorepo/telesphorepo:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - telesphorepo-data:/data
      - telesphorepo-backups:/backups

volumes:
  telesphorepo-data:
    name: telesphorepo-data
  telesphorepo-backups:
    name: telesphorepo-backups

Start the server.
Terminal window
```
docker compose up -d
```
Copy the admin password from the log.
Terminal window
```
docker compose logs telesphorepo
```

Podman

Start the server.

podman run -d --name telesphorepo -p 127.0.0.1:8080:8080 -v telesphorepo-data:/data -v telesphorepo-backups:/backups ghcr.io/telesphorepo/telesphorepo:latest

Copy the admin password from the log.
Terminal window
```
podman logs telesphorepo
```

Download the program

Download telesphorepo-server for your system from GitHub Releases, and unpack it.
Start the server, and copy the admin password that it shows.
Terminal window
```
TR_LISTEN=127.0.0.1:8080 ./telesphorepo-server serve
```

The data is in ./data, next to where you started it.

Serve over HTTPS

Put a web server in front. It gets the certificate and passes each request on to localhost:8080.

Caddy

Caddy gets and renews the certificate itself.

Install Caddy. On Debian and Ubuntu:
Terminal window
```
sudo apt install caddy
```
For other systems, see Install Caddy.
Put this in /etc/caddy/Caddyfile, in place of what is there.
/etc/caddy/Caddyfile
```
repo.example.com {
    reverse_proxy localhost:8080
}
```
Reload Caddy.
Terminal window
```
sudo systemctl reload caddy
```

nginx

Install nginx and Certbot. On Debian and Ubuntu:
Terminal window
```
sudo apt install nginx certbot python3-certbot-nginx
```

Save this as /etc/nginx/conf.d/telesphorepo.conf.

server {
    listen 80;
    server_name repo.example.com;

    client_max_body_size 0;
    proxy_request_buffering off;
    proxy_buffering off;
    proxy_read_timeout 1h;
    proxy_send_timeout 1h;

    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;
    }
}

Get a certificate. Certbot adds HTTPS to the file and reloads nginx.
Terminal window
```
sudo certbot --nginx -d repo.example.com --redirect
```

Apache

Install Apache and Certbot. On Debian and Ubuntu:
Terminal window
```
sudo apt install apache2 certbot python3-certbot-apache
```
Turn on the proxy modules.
Terminal window
```
sudo a2enmod proxy proxy_http headers
```

Save this as /etc/apache2/sites-available/telesphorepo.conf.

<VirtualHost *:80>
    ServerName repo.example.com

    ProxyPreserveHost On
    AllowEncodedSlashes NoDecode
    ProxyPass / http://127.0.0.1:8080/ nocanon
    RequestHeader set X-Forwarded-Proto expr=%{REQUEST_SCHEME}

    LimitRequestBody 0
    ProxyTimeout 3600
</VirtualHost>

Turn on the site.

sudo a2ensite telesphorepo
sudo systemctl reload apache2

Get a certificate. Certbot adds HTTPS to the site and reloads Apache.
Terminal window
```
sudo certbot --apache -d repo.example.com --redirect
```

Another proxy

Set up your proxy to:

pass each request on to localhost:8080, with its Host header,
set X-Forwarded-For and X-Forwarded-Proto,
take bodies of any size, or at least the Max upload size (2 GiB by default),
stream uploads and downloads, and wait up to an hour,
keep %2F in paths as it is. npm needs it.

It may speak HTTP/1.1 or HTTP/2 to the server.

No proxy? Set TR_TLS_CERT_FILE and TR_TLS_KEY_FILE to PEM files, and the server serves HTTPS itself.

Open your address, such as https://repo.example.com. On your own computer, open http://localhost:8080.
Sign in as admin, with the password from the log.
Add your authenticator app when the page asks. Under Authenticator app, click Add, scan the code, and type the code from your phone.

Trust the proxy

The server then sees the real address of each client. The audit log and the network rules need it.

Open Settings › Network and proxy.
Under Detected proxies, click Trust on the row of your web server.
Click Save, then Save changes.

Set the public address

Your first sign-in sets the public address. Check it once.

Open Settings › General.
Check that Public base URL is the address that people use, such as https://repo.example.com. Fix it and click Save if not.

Snippets, CI jobs and passkeys use this address.

Next steps

If something goes wrong

You lost the admin password

Set a new one, and type it at the prompt:

docker exec -it telesphorepo /telesphorepo-server user passwd admin

Your data is gone after you removed the container

The data lives in the telesphorepo-data volume. Start the server on it again, or restore a backup.

The browser signs you out at once on plain HTTP

The browser drops the session cookie on plain HTTP, except at localhost. Serve the server over HTTPS.

Uploads through the proxy fail with 413

Let the proxy take bodies of any size: client_max_body_size 0 in nginx, LimitRequestBody 0 in Apache.

The page shows no Detected proxies

Open the server once at your HTTPS address, then reload the page.

Cloudflare sits in front of your web server

Under Where your proxy is, also tick Cloudflare. Then see Push large images.