proxy/docs/installation.md

layout, title

layout	title
default	Installation

Installation Guide

← Back to Home

Quick Install (Recommended)

For modern Debian-based systems (Ubuntu 20.04+, Debian 11+):

wget -O - https://raw.githubusercontent.com/theta42/proxy/master/ops/install.sh | sudo bash

This automated installer will:

• Install Node.js 20.x
• Install OpenResty and required dependencies
• Install and configure Redis
• Set up SSL fallback certificates
• Install Lua dependencies
• Clone and install the proxy application
• Configure systemd service
• Start the proxy service

Manual Installation

System Requirements

• Modern Linux distribution (Ubuntu 20.04+, Debian 11+, or equivalent)
• Root access
• Inbound internet access for Let's Encrypt validation
• Minimum 1GB RAM, 10GB disk space

Step 1: Install Dependencies

Ubuntu/Debian:

apt install libpam0g-dev build-essential redis-server luarocks -y

Step 2: Install Node.js 20.x

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | \
  sudo tee /etc/apt/sources.list.d/nodesource.list

apt update && apt install nodejs -y

Verify installation:

node --version  # Should show v20.x.x
npm --version

Step 3: Install OpenResty

openresty.org ships distinct trees for Debian and Ubuntu — use /package/debian on Debian and /package/ubuntu on Ubuntu (using the Ubuntu tree with a Debian codename worked on older Debian by coincidence; trixie lives under /debian).

# Debian:  OR_PATH=package/debian    Ubuntu/Mint:  OR_PATH=package/ubuntu
. /etc/os-release
case "$ID" in debian) OR_PATH=package/debian;; *) OR_PATH=package/ubuntu;; esac

wget -O - https://openresty.org/package/pubkey.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/openresty.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/${OR_PATH} $(lsb_release -sc) main" | \
  sudo tee /etc/apt/sources.list.d/openresty.list

Debian 13 (trixie): apt's sequoia GPG backend rejects SHA-1 signatures by default, and the OpenResty signing key is still SHA-1, so apt update will refuse the repo. Extend the SHA-1 acceptance window before updating:

sudo mkdir -p /etc/crypto-policies/back-ends
sudo cp /usr/share/apt/default-sequoia.config /etc/crypto-policies/back-ends/apt-sequoia.config
sudo sed -i 's/2026-02-01/2028-02-01/' /etc/crypto-policies/back-ends/apt-sequoia.config

(The default-sequoia.config file only ships on Debian 13+, so this is a no-op on older releases. ops/install.sh applies this automatically.)

apt update && apt install openresty -y

Step 4: Install Lua Dependencies

luarocks install lua-resty-auto-ssl
luarocks install luasocket

Step 5: SSL Configuration

Create fallback SSL certificates:

mkdir -p /etc/ssl/

openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 \
  -subj '/CN=sni-support-required-for-valid-ssl' \
  -keyout /etc/ssl/resty-auto-ssl-fallback.key \
  -out /etc/ssl/resty-auto-ssl-fallback.crt

Step 6: Configure OpenResty

Clone the repository and copy configuration files:

cd /var/www
git clone https://github.com/theta42/proxy.git
cd proxy

# Copy nginx configs
mkdir -p /etc/openresty/sites-enabled/
cp ops/nginx_conf/nginx.conf /etc/openresty/nginx.conf
cp ops/nginx_conf/autossl.conf /etc/openresty/autossl.conf
cp ops/nginx_conf/proxy.conf /etc/openresty/sites-enabled/000-proxy
cp ops/nginx_conf/targetinfo.lua /usr/local/openresty/lualib/targetinfo.lua

Step 7: Install Application

cd /var/www/proxy/nodejs
npm install

Step 8: Configure Systemd Service

cp /var/www/proxy/ops/proxy.service /etc/systemd/system/proxy.service
systemctl daemon-reload
systemctl enable proxy.service
systemctl start proxy.service

Verify service is running:

systemctl status proxy.service

Step 9: Initial Setup

The proxy API will be available on port 3000 by default. You'll need to:

1. Create your first user account
2. Configure DNS providers (for wildcard SSL)
3. Add your first host

See the API Reference for details.

Configuration

Environment Variables

• NODE_ENV - Set to production for production deployments
• NODE_PORT - Override default port (default: 3000)

Redis Configuration

The proxy uses Redis with the prefix proxy_. To change this, edit nodejs/conf/base.js:

redis: {
  prefix: 'proxy_'
}

OpenResty Configuration

Key configuration files in /etc/openresty/:

• nginx.conf - Main nginx configuration
• autossl.conf - Let's Encrypt HTTP-01 challenge handler
• sites-enabled/000-proxy - Proxy server configuration

Unix Socket

The proxy communicates with OpenResty via Unix socket at:

/var/run/proxy_lookup.socket

This path is configurable in nodejs/conf/base.js.

Troubleshooting

Service won't start

Check logs:

journalctl -u proxy.service -f

Common issues:

• Port 3000 already in use
• Redis not running: systemctl status redis-server
• Permission issues: Service must run as root for user management

SSL certificates not working

Check OpenResty logs:

tail -f /var/log/nginx/error.log

Common issues:

• Firewall blocking ports 80/443
• DNS not pointing to server
• Let's Encrypt rate limits exceeded

Host lookup not working

Check Unix socket:

ls -la /var/run/proxy_lookup.socket
# Should show srwxrwxrwx (socket permissions)

Test lookup:

echo '{"domain":"example.com"}' | nc -U /var/run/proxy_lookup.socket

Next Steps

• Configure DNS Providers for wildcard SSL
• Add your first host
• Set up the web interface

← Back to Home