> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment (VDS)

> Publish your theme on your own VDS/VPS with Node.js, PM2 and Nginx.

> [!WARNING]
>
> **It does not work on LeaderOS Web Hosting (shared hosting).** Next.js themes need a continuously running **Node.js process**, and shared hosting cannot run a Node.js server. You must publish your theme on your own **VDS/VPS** or a platform that supports Node.js. Your LeaderOS site itself (API, admin panel) keeps running on its current hosting.

## Architecture

```
Player ──► https://shop.example.com  (VDS: Nginx → Next.js :3000)
                 │  server to server
                 ▼
          https://play.example.com/headless/v1  (LeaderOS site, existing hosting)
```

* **LeaderOS site** (`play.example.com`): API, admin panel, payment callbacks. It must keep running.
* **Theme** (`shop.example.com`): the address players visit. It pulls data from LeaderOS.

## Requirements

| Requirement | Recommendation |
| - | - |
| OS | Ubuntu 22.04 / 24.04 (or similar Linux) |
| Resources | At least 1 vCPU, 1–2 GB RAM (2 GB recommended for building) |
| Node.js | 20 LTS or newer (minimum 18.18) |
| Domain | A domain/subdomain for the theme (e.g. `shop.example.com`) pointing to the server |
| Access | SSH with root or sudo |

## 1. Prepare the server

```bash theme={null}
sudo apt update && sudo apt upgrade -y
sudo apt install -y nginx git curl

# Node.js 20 (NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# PM2 (process manager)
sudo npm install -g pm2
```

## 2. Get the project onto the server

> [tab] With Git
>
> ```bash theme={null}
> cd /var/www
> sudo git clone https://github.com/user/my-theme.git
> sudo chown -R $USER:$USER my-theme
> cd my-theme
> ```

> [tab] Uploading files
>
> Send the project with `scp`/`rsync`, excluding `node_modules` and `.next`:
>
> ```bash theme={null}
> rsync -av --exclude node_modules --exclude .next ./my-theme/ user@server:/var/www/my-theme/
> ```

## 3. Environment variables

Create `/var/www/my-theme/.env.production` on the server:

```bash theme={null}
LEADEROS_URL=https://play.example.com
LEADEROS_PUBLIC_KEY=pk_live_XXXXXXXX
SITE_URL=https://shop.example.com
```

| Variable | Description |
| - | - |
| `LEADEROS_URL` | Address of your LeaderOS site |
| `LEADEROS_PUBLIC_KEY` | The key you copied from the panel |
| `SITE_URL` | Public address of your theme (for sitemap and robots) |

> [!NOTE]
>
> Do not add `.env*` files to Git. If you regenerate the key, update this file and restart the app.

## 4. Build and start

```bash theme={null}
npm ci          # or npm install
npm run build
pm2 start npm --name leaderos-theme -- start
pm2 save
pm2 startup     # run the command it prints: the app starts again after a reboot
```

The app listens on port `3000` by default. For another port: `PORT=3100 pm2 start npm --name leaderos-theme -- start`.

## 5. Nginx reverse proxy

`/etc/nginx/sites-available/leaderos-theme`:

```nginx theme={null}
server {
    listen 80;
    server_name shop.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/leaderos-theme /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

> [!TIP]
>
> The `X-Forwarded-For` header matters: the theme forwards the visitor's real IP address to LeaderOS with it (registration limit, logs and so on). If you use Cloudflare, make sure the real IP is passed through correctly.

## 6. SSL (HTTPS)

```bash theme={null}
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d shop.example.com
```

The certificate renews automatically. HTTPS is **required** on a live site; otherwise cookies and payment providers cause problems.

## 7. Configure the LeaderOS panel

In **Settings → Headless API**:

**1. Frontend URL**

Enter `https://shop.example.com`. E-mail links and payment returns now come to your theme.

**2. Page paths**

Leave the defaults if you use the template's; if you changed them, enter the same paths.

**3. Origins**

Not needed for the template, which uses the proxy. If you call the API directly from the browser, add `https://shop.example.com`. **"Allow all origins" must be off.**

## 8. Payment providers

* **Browser return**: after paying, the player returns to your theme's `/payment/success` and `/payment/error` pages.
* **Server notifications (callbacks/webhooks)** keep arriving at LeaderOS: the PayTR notification URL, Stripe/Shopier webhooks and so on. **Do not change your existing settings**; they must still point to your LeaderOS site.
* Test the payment flow end to end with a small amount before going live.

## Updating

```bash theme={null}
cd /var/www/my-theme
git pull
npm ci
npm run build
pm2 restart leaderos-theme
```

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| 502 Bad Gateway | The app is not running: `pm2 logs leaderos-theme` |
| Empty pages / `INVALID_API_KEY` | The key in `.env.production` is wrong or was regenerated |
| `LICENSE_INVALID` (402) | License/domain of your LeaderOS site |
| E-mail links go to the old address | Frontend URL not set in the panel |
| Out-of-memory during build | Add 2 GB RAM or swap |
| Session drops after login | No HTTPS, or the proxy does not forward `X-Forwarded-Proto` |

> [!WARNING]
>
> Check the "Powered by LeaderOS" link in the footer before going live. If it is hidden, the page is replaced with a notice.


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