# Run the server

> Start Telesphorepo, serve it over HTTPS, sign in, trust the proxy and set the public address.

Source: https://docs.telesphorepo.com/run-the-server/

To try it on your own computer, [Start the server](#start-the-server) and [Sign in](#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

1. Start the server.

   ```sh
   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
   ```

2. Copy the admin password from the log.

   ```sh
   docker logs telesphorepo
   ```

### Docker Compose

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

   ```yaml title="compose.yaml"
   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
   ```

2. Start the server.

   ```sh
   docker compose up -d
   ```

3. Copy the admin password from the log.

   ```sh
   docker compose logs telesphorepo
   ```

### Podman

1. Start the server.

   ```sh
   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
   ```

2. Copy the admin password from the log.

   ```sh
   podman logs telesphorepo
   ```

### Download the program

1. Download `telesphorepo-server` for your system from [GitHub Releases](https://github.com/Telesphorepo/Telesphorepo/releases), and unpack it.

2. Start the server, and copy the admin password that it shows.

   ```sh
   TR_LISTEN=127.0.0.1:8080 ./telesphorepo-server serve
   ```

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

> Caution
>
> Always keep the `telesphorepo-data` volume. It holds all your data.

## Serve over HTTPS

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

### Caddy

[Caddy](https://caddyserver.com) gets and renews the certificate itself.

1. Install Caddy. On Debian and Ubuntu:

   ```sh
   sudo apt install caddy
   ```

   For other systems, see [Install Caddy](https://caddyserver.com/docs/install).

2. Put this in `/etc/caddy/Caddyfile`, in place of what is there.

   ```text title="/etc/caddy/Caddyfile"
   repo.example.com {
       reverse_proxy localhost:8080
   }
   ```

3. Reload Caddy.

   ```sh
   sudo systemctl reload caddy
   ```

### nginx

1. Install nginx and Certbot. On Debian and Ubuntu:

   ```sh
   sudo apt install nginx certbot python3-certbot-nginx
   ```

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

   ```nginx title="/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;
       }
   }
   ```

3. Get a certificate. Certbot adds HTTPS to the file and reloads nginx.

   ```sh
   sudo certbot --nginx -d repo.example.com --redirect
   ```

### Apache

1. Install Apache and Certbot. On Debian and Ubuntu:

   ```sh
   sudo apt install apache2 certbot python3-certbot-apache
   ```

2. Turn on the proxy modules.

   ```sh
   sudo a2enmod proxy proxy_http headers
   ```

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

   ```apache title="/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>
   ```

4. Turn on the site.

   ```sh
   sudo a2ensite telesphorepo
   sudo systemctl reload apache2
   ```

5. Get a certificate. Certbot adds HTTPS to the site and reloads Apache.

   ```sh
   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.

## Sign in

1. Open your address, such as `https://repo.example.com`. On your own computer, open `http://localhost:8080`.

2. Sign in as `admin`, with the password from the log.

3. 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](/repositories-and-access/#limit-where-requests-come-from) need it.

1. Open **Settings** › **Network and proxy**.

2. Under **Detected proxies**, click **Trust** on the row of your web server.

3. Click **Save**, then **Save changes**.

## Set the public address

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

1. Open **Settings** › **General**.

2. 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

- [Store files in R2 or S3](/store-files-in-r2/)
- [Back up and restore](/back-up-and-restore/)
- [Upgrade the server](/upgrade/)
- [Push large images](/push-large-images/)
- [Repositories and access](/repositories-and-access/)

## If something goes wrong

You lost the admin password

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

```sh
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](/back-up-and-restore/#restore).

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](/push-large-images/).