Reverse Proxy

FlatRun uses Nginx as a reverse proxy to route incoming traffic to your deployments based on domain names. This enables you to run multiple applications on a single server, each with its own domain.

How It Works

1. A request comes in for blog.example.com
2. Nginx receives the request on port 80/443
3. Nginx checks its virtual host configuration
4. The request is forwarded to the appropriate container
5. The container's response is sent back to the client

Nginx Configuration

Configure Nginx in your agent config:

nginx:
  enabled: true
  image: nginx:alpine
  container_name: nginx
  config_path: ""
  reload_command: "nginx -s reload"
  external: false
  container_webroot_path: /usr/share/nginx/html

Option	Description
enabled	Enable Nginx integration
image	Docker image for Nginx
container_name	Name of the Nginx container
config_path	Path to config directory (auto-detected if empty)
reload_command	Command to reload Nginx config
external	Use external Nginx (not managed by FlatRun)

Directory Structure

Nginx configuration is stored in the deployments path:

/var/flatrun/deployments/
└── nginx/
    ├── docker-compose.yml    # Nginx container definition
    ├── conf.d/               # Virtual host configs
    │   ├── blog.example.com.conf
    │   └── api.example.com.conf
    ├── certs/                # SSL certificates
    │   └── live/
    │       └── example.com/
    └── html/                 # Static files, certbot webroot

Virtual Host Configuration

FlatRun automatically generates virtual host configurations when you set up proxy for a deployment. A typical config looks like:

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

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name blog.example.com;

    ssl_certificate /etc/nginx/certs/live/blog.example.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/live/blog.example.com/privkey.pem;

    location / {
        proxy_pass http://my-blog-wordpress:80;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Setting Up Proxy for a Deployment

Via UI

1. Go to Deployments and select your deployment
2. Go to the Overview tab
3. In the Domain & SSL section, click "Set Up Proxy"
4. Enter the domain name
5. Select the container port
6. Optionally enable SSL
7. Click "Save"

Via API

curl -X POST "http://localhost:8090/api/proxy/setup/my-blog" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "blog.example.com",
    "port": 80,
    "ssl": true
  }'

Via service.yml

name: My Blog
networking:
  expose: true
  domain: blog.example.com
  port: 80

ssl:
  enabled: true
  auto_renew: true

Proxy Network

For Nginx to communicate with your deployment containers, they must be on the same Docker network. FlatRun uses a proxy network for this purpose.

# Create the proxy network (if not exists)
docker network create proxy

# Deployments should connect to this network
services:
  web:
    image: myapp
    networks:
      - default
      - proxy

networks:
  proxy:
    external: true

External Nginx

If you have an existing Nginx installation (on the host or another container), set external: true:

nginx:
  enabled: true
  external: true
  config_path: /etc/nginx/conf.d
  reload_command: "systemctl reload nginx"

FlatRun will generate config files but won't manage the Nginx container.

Load Balancing

For deployments with multiple replicas, configure an upstream block:

upstream myapp_backend {
    server myapp_1:3000;
    server myapp_2:3000;
    server myapp_3:3000;
}

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

    location / {
        proxy_pass http://myapp_backend;
    }
}

WebSocket Support

The default configuration includes WebSocket support through the Upgrade headers. No additional configuration is needed.

Custom Nginx Configuration

You can add custom configuration by creating files in the conf.d directory. FlatRun won't overwrite files it didn't create.

# Custom rate limiting
# /var/flatrun/deployments/nginx/conf.d/rate-limit.conf
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

# Custom headers
# /var/flatrun/deployments/nginx/conf.d/security-headers.conf
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;

Troubleshooting

502 Bad Gateway

• Container is not running
• Container not on the proxy network
• Wrong port in proxy configuration
• Container name mismatch

Config Not Reloading

• Check Nginx syntax: docker exec nginx nginx -t
• Manually reload: docker exec nginx nginx -s reload
• Check FlatRun logs for errors

Domain Not Resolving

• Ensure DNS points to your server
• Check that port 80/443 is open in firewall
• Verify Nginx is listening on correct ports