> ## Documentation Index
> Fetch the complete documentation index at: https://diced-zipline.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Domains

> Configure multiple domains and custom upload domains for Zipline

Zipline supports multiple domains, allowing you to serve files from different domains or subdomains. This is useful for branding, organizing uploads, or providing different access URLs.

## How Custom Domains Work

Zipline can serve files from multiple domains simultaneously. When configured:

* Files can be accessed via any configured domain
* You can set a default domain for new uploads
* Users can choose which domain to use for their uploads
* All domains must point to your Zipline instance

## Configuration

### Setting the Default Domain

The default domain is used for generating URLs when uploading files:

```bash theme={null}
CORE_DEFAULT_DOMAIN=files.example.com
```

This domain will be used in:

* File URLs returned by the API
* Shortened URLs
* Email notifications and webhooks

### Configuring Multiple Domains

You can configure additional domains that Zipline will accept requests from:

```bash theme={null}
DOMAINS=files.example.com,cdn.example.com,uploads.example.org
```

> [!NOTE]
>
> The `DOMAINS` configuration is stored in the database (see `prisma/schema.prisma:149`). You can also manage domains through the admin dashboard after initial setup.

## DNS Configuration

**1. Add DNS A/AAAA records**

For each domain, create DNS records pointing to your server:

**A Record (IPv4):**

```
files.example.com    A    203.0.113.1
cdn.example.com      A    203.0.113.1
```

**AAAA Record (IPv6):**

```
files.example.com    AAAA    2001:db8::1
cdn.example.com      AAAA    2001:db8::1
```

**2. Wait for DNS propagation**

DNS changes can take up to 48 hours to propagate globally, but usually complete within a few minutes to hours.

Verify DNS propagation:

```bash theme={null}
nslookup files.example.com
nslookup cdn.example.com
```

## Reverse Proxy Configuration

Configure your reverse proxy to accept requests from all domains.

### Nginx

```nginx theme={null}
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    
    # List all domains
    server_name files.example.com cdn.example.com uploads.example.org;

    ssl_certificate /etc/ssl/certs/your-cert.crt;
    ssl_certificate_key /etc/ssl/private/your-key.key;

    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}
```

### Caddy

```caddy theme={null}
files.example.com, cdn.example.com, uploads.example.org {
    reverse_proxy localhost:3000
}
```

> [!TIP]
>
> Caddy will automatically obtain separate SSL certificates for each domain!

### Apache

```apache theme={null}
<VirtualHost *:443>
    ServerName files.example.com
    ServerAlias cdn.example.com uploads.example.org

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/your-cert.crt
    SSLCertificateKeyFile /etc/ssl/private/your-key.key

    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
</VirtualHost>
```

## SSL Certificates for Multiple Domains

### Let's Encrypt with Certbot

Obtain a certificate covering all domains:

```bash theme={null}
sudo certbot --nginx -d files.example.com -d cdn.example.com -d uploads.example.org
```

Or for Apache:

```bash theme={null}
sudo certbot --apache -d files.example.com -d cdn.example.com -d uploads.example.org
```

### Caddy (Automatic)

Caddy automatically obtains and manages certificates for all configured domains:

```caddy theme={null}
files.example.com, cdn.example.com, uploads.example.org {
    reverse_proxy localhost:3000
}
```

### Cloudflare

If using Cloudflare:

1. Add all domains to your Cloudflare account
2. Enable SSL/TLS (Full or Full (strict) mode)
3. Configure DNS records for each domain
4. Cloudflare automatically provides SSL certificates

## Use Cases

### Separate Upload and CDN Domains

Use different domains for uploads and file delivery:

```bash theme={null}
CORE_DEFAULT_DOMAIN=uploads.example.com
DOMAINS=uploads.example.com,cdn.example.com
```

* `uploads.example.com` - Admin interface and uploads
* `cdn.example.com` - Public file access

> [!TIP]
>
> This allows you to apply different caching rules or CDN configurations to your file delivery domain.

### Multiple Brands/Projects

Use different domains for different projects:

```bash theme={null}
DOMAINS=files.project-a.com,files.project-b.com,shared.cdn.com
```

Users can choose which domain to use when uploading files.

### Regional Domains

Provide region-specific domains:

```bash theme={null}
DOMAINS=us.example.com,eu.example.com,asia.example.com
```

Combine with GeoDNS to route users to the nearest server.

## Managing Domains via Admin Dashboard

After initial setup, you can manage domains through the Zipline admin interface:

1. Log in as an administrator
2. Navigate to **Settings** → **Server**
3. Scroll to **Domains** section
4. Add or remove domains as needed
5. Click **Save**

> [!WARNING]
>
> Ensure DNS and reverse proxy configurations are updated before adding domains in the dashboard, or files may not be accessible.

## HTTPS URL Generation

When using custom domains with HTTPS:

```bash theme={null}
CORE_RETURN_HTTPS_URLS=true
CORE_DEFAULT_DOMAIN=files.example.com
CORE_TRUST_PROXY=true
```

This ensures:

* File URLs use `https://` instead of `http://`
* Correct domain is used in generated URLs
* Proxy headers are respected

## Wildcard Domains

For subdomain-based file serving (e.g., `user1.files.example.com`, `user2.files.example.com`):

### DNS Configuration

Create a wildcard DNS record:

```
*.files.example.com    A    203.0.113.1
```

### Reverse Proxy Configuration

**Nginx:**

```nginx theme={null}
server {
    listen 443 ssl http2;
    server_name *.files.example.com;

    ssl_certificate /etc/ssl/certs/wildcard-cert.crt;
    ssl_certificate_key /etc/ssl/private/wildcard-key.key;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

**Caddy:**

```caddy theme={null}
*.files.example.com {
    reverse_proxy localhost:3000
}
```

### Wildcard SSL Certificate

**Certbot with DNS challenge:**

```bash theme={null}
sudo certbot certonly --manual --preferred-challenges dns -d "*.files.example.com"
```

> [!NOTE]
>
> Wildcard certificates require DNS validation. You'll need to add a TXT record during the challenge.

## Troubleshooting

> **Files not accessible via new domain**
>
> Check:
>
> * DNS records point to correct server IP: `nslookup your-domain.com`
> * Domain is listed in `DOMAINS` configuration or admin dashboard
> * Reverse proxy accepts requests for the domain
> * SSL certificate covers the domain
> * Firewall allows traffic on ports 80/443

> **Wrong domain in file URLs**
>
> This happens when `CORE_DEFAULT_DOMAIN` isn't set correctly:
>
> * Verify `CORE_DEFAULT_DOMAIN` matches your primary domain
> * Restart Zipline after changing configuration
> * Clear any cached URLs in ShareX or other clients

> **SSL certificate errors on additional domains**
>
> * Ensure SSL certificate covers all domains (use SAN certificate or separate certs)
> * For Let's Encrypt, include all domains in the `certbot` command
> * For Caddy, it automatically handles multiple domains
> * Check certificate details: `openssl s_client -connect domain.com:443 -servername domain.com`

> **Cloudflare 'too many redirects' error**
>
> This occurs when Cloudflare SSL mode is misconfigured:
>
> * Set Cloudflare SSL mode to **Full** or **Full (strict)**
> * Ensure `CORE_RETURN_HTTPS_URLS=true` is set
> * Verify reverse proxy doesn't force HTTP redirects

> **Domain works but shows wrong content**
>
> * Check reverse proxy `Host` header is being passed: `proxy_set_header Host $host;`
> * Verify `CORE_TRUST_PROXY=true` is set
> * Ensure no conflicting server blocks in reverse proxy config

## Best Practices

* **Use descriptive domains**: `files.example.com`, `cdn.example.com` instead of random subdomains
* **Plan your structure**: Decide on domain purposes before deploying
* **Document your setup**: Keep track of which domains serve which purposes
* **Monitor all domains**: Set up monitoring for all configured domains
* **Consistent SSL**: Ensure all domains have valid SSL certificates
* **DNS TTL**: Use reasonable TTL values (e.g., 300-3600 seconds) for easier updates

> [!TIP]
>
> Consider using a CDN like Cloudflare, CloudFront, or BunnyCDN in front of your custom domains for better performance and DDoS protection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.