​
Set Up Reverse Proxy

A reverse proxy is essential for providing secure access to your Oxy deployment. We recommend using Caddy, which automatically handles SSL certificate management.

1

Install Caddy

Install Caddy on your server:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update -y
sudo apt install -y caddy
2

Create Basic Caddyfile

Create a basic Caddyfile to configure your reverse proxy:

(reverse_proxy_app) {
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1
        transport http {
            versions 1.1 2 h2c
        }
    }
}

(reverse_proxy_oauth2) {
    reverse_proxy 127.0.0.1:4180 {
        header_up x-real-ip {remote_host}
        header_up x-forwarded-uri {uri}
    }
}

your-domain.com {
    @static_assets {
        path *.js *.css *.svg *.json *.gif *.wasm
    }

    handle /auth        import reverse_proxy_oauth2
    }

    # Defer Authorization header for static assets
    handle @static_assets {
        import reverse_proxy_app
    }

    handle {
        @except not path 
        forward_auth @except 127.0.0.1:4180 {
            uri /auth
            header_up x-real-ip {remote_host}
            copy_headers x-auth-request-user x-auth-request-email x-auth-request-access-token authorization

            @error status 401
            handle_response @error {
                redir * 
            }
        }

        import reverse_proxy_app
    }
}

Replace your-domain.com with your actual domain name or use localhost for local testing. Adjust the port if your Oxy instance listens on a different port.

Caddy automatically manages SSL certificates for you, making HTTPS setup effortless. Just make sure your domain’s DNS is properly configured to point to your server.

3

Set Up Caddy as a Service

Configure Caddy to run as a systemd service:

cat <<EOF | sudo tee /etc/systemd/system/caddy.service
[Unit]
Description=Caddy Web Server
After=network.target

[Service]
User=root
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile
Restart=on-failure
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable caddy
sudo systemctl start caddy
4

Configure Firewall for HTTP/HTTPS

Update your firewall to allow HTTP and HTTPS traffic:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable

These ports are necessary for Caddy to obtain and renew SSL certificates (port 80) and serve your site securely (port 443).

Now that you have a reverse proxy set up with automatic HTTPS, you can proceed to set up your Oxy workspace and repository.

​
Data Persistence Considerations

When setting up your Oxy deployment behind a reverse proxy, it’s important to properly configure data persistence:

  • Oxy stores its state data (including SQLite database files) at the location specified by OXY_STATE_DIR
  • If not specified, data defaults to ~/.local/share/oxy/ in the user’s home directory
  • Ensure this directory is backed by reliable storage and included in your backup strategy
  • For high-availability setups, consider using network-attached storage that can be accessed by multiple instances

Your reverse proxy configuration remains unchanged regardless of where Oxy stores its data, but ensuring proper data persistence is critical for production deployments.