Install the main server (Operations Guide)

This document takes you from the download to the first login.

Before you start

The server meets the Requirements.
You are logged in as root over SSH.
Your license key is at hand.
The server is empty. Do not run the installer on a server that already holds a panel. See the section "Running the installer again" below.
The installer enables the ufw firewall. It keeps port 22 and every port that your SSH service listens on open.

Warning. The installer is for a new installation. It is not a repair or update tool. Update the panel from the dashboard as described in Updates and rollback.

Steps

1. Download the installer and the checksum list

bash

cd /root
wget https://api.xtreamgo.io/install/install.sh
wget https://api.xtreamgo.io/install/SHA256SUMS

2. Verify the checksum

bash

sha256sum -c --ignore-missing SHA256SUMS

Expected output: install.sh: OK.

The list also covers docker-compose.yml, nginx/nginx.conf, ssl-setup.sh, xtreamgo-agent and images/xtreamgo-bundle.tar.gz. The installer checks the image bundle against this list by itself and stops when it does not match. It does not check the other files. The checksum list comes from the same server as the files, so it detects a damaged download. It does not prove who published the files.

3. Run the installer

bash

sudo bash install.sh

4. Answer the questions

Prompt	What to enter
`Select Language / Dil Secin`	1 English, 2 Turkce, 3 Deutsch, 4 Francais, 5 Espanol, 6 Italiano.
`License Key:`	Your license key. The installer validates it with the license server before it changes anything.
`HTTP Port [80]:`	Press Enter for 80, or type another port for the Xtream Codes API and streams.
`Domain (optional, leave blank):`	A domain that already points at this server, or leave empty.
`Continue? (y/n) [y]:`	Check the summary, then press Enter.

The server IP is detected automatically and shown as Server IP address: <ip>.

5. Wait for the six steps

Step	Title on screen	What happens
1/6	System Update	`apt-get update` and `apt-get upgrade`. Installs `curl wget ca-certificates gnupg lsb-release ufw ffmpeg`.
2/6	Docker Installation	Installs Docker from `get.docker.com` when it is missing. Allows port 22, every port the SSH service listens on, ports 80, 443, 1935 and your custom HTTP port in `ufw`, then enables `ufw`.
3/6	Downloading Files	Creates `/home/xtreamgo`, downloads `docker-compose.yml`, `nginx/nginx.conf` and the maintenance scripts. Pulls `nginx:1.25-alpine` and `redis:7-alpine`. Downloads the image bundle, checks its SHA-256 sum and loads the images `db`, `api`, `frontend`, `portal`, `website`.
4/6	Configuration & License Activation	Generates the database passwords and secrets, writes `/home/xtreamgo/.env.production`, activates the license and writes `/home/xtreamgo/CREDENTIALS.txt`.
5/6	Starting Services	Checks for an existing panel (see "Running the installer again"). Starts all containers. Waits up to 15 minutes for the API to become healthy. The first start applies all database migrations, which can take up to 10 minutes. Creates the `xtreamgo.service` systemd unit and the `xtreamgo` command.
6/6	Installation Complete!	Prints the panel address, the admin user and password, and the container status. The first line of the box, `CMS Admin:`, is the address of your admin panel.

Between step 5 and step 6 the installer sets up database access for load balancers and prints Database privacy check. The expected line is Database not reachable from the internet (127.0.0.1 and LB whitelist only).

6. Answer the two optional questions

Prompt	Recommended answer
`Add LB now? (y/n) [n]:`	Press Enter (no). Add load balancers from the panel as described in Add a load balancer server. The panel writes the complete agent configuration.
`Configure Cloudflare now? (y/n) [n]:`	Press Enter (no) unless you have read HTTPS and domain.

7. Log in

Open http://<server-ip> or http://<your-domain> in a browser.
User name: admin.
Password: the value shown in the final box of the installer. It is also stored on the server:

bash

cat /home/xtreamgo/CREDENTIALS.txt

The file is readable by root only. It also holds the database passwords and the JWT secret, which signs login sessions. Copy it to a safe place. The first address in the file, CMS Admin:, is the address of your admin panel.

8. Complete the first-run wizard

On the first login the panel opens a setup wizard. Its steps are:

Welcome.
Admin Account. Enter the current password and a new password. This step is required.
Login CAPTCHA with Cloudflare Turnstile. Optional.
Telegram notification bot. Optional.
Email (SMTP). Optional.
Completed.

You can skip the optional steps and configure them later under Settings.

In the Admin Account step, use the password from CREDENTIALS.txt as the current password. The text of this step mentions a default admin/admin login. That login does not exist on your server. The installer created the admin account with a random 16 character password.

9. Change the admin password later

Use the Change Password function of your admin account. The panel asks for the current password. The new password must have at least 6 characters. Possible messages are Current password is incorrect and New password must be at least 6 characters.

CREDENTIALS.txt is not updated when you change the password in the panel. The ADMIN_PASSWORD line in .env.production is only used when the database has no users at all. Editing that line later does not change the password of an existing admin account.

Unattended installation

The installer also accepts flags:

bash

sudo bash install.sh --non-interactive --license-key=<key> [--server-ip=<ip>] [--xc-port=<port>] [--domain=<domain>] [--lang=en]

In this mode the installer asks nothing, skips the two optional questions and reboots the server 10 seconds after a complete start. It prints REBOOT:SKIPPED when a container is missing.

The flag --reinstall-wipe works in both modes. It is described in the next section.

Running the installer again

The first thing the installer does, before it changes anything, is look for containers with xtreamgo in their name. What happens next depends on what it finds.

Situation	Result
No such container	Normal installation.
A previous attempt that never went into use	The installer continues. In step 5/6 it prints `Cleaning up previous installation...`, runs `docker compose down -v`, empties `/home/xtreamgo/db` and installs again.
A panel that is in use, without `--reinstall-wipe`	The installer stops with exit code 1 before the system update, the downloads and the configuration step. Nothing on the server is changed.
A panel that is in use, with `--reinstall-wipe`	The installer removes the panel containers and runs `docker compose down -v`. This deletes the Docker volumes, including the database, the media files and the backups made in the panel. Then it installs from scratch.

How the installer decides that a panel is in use:

The database container runs. The installer adds up the admin and reseller accounts that have logged in at least once, the subscriber lines and the streams. Any number above 0 means in use.
The database container does not answer. A database volume that is older than two hours means in use.

The refusal prints:

text

An XtreamGo panel that is already in use was found on this server.
Nothing was changed. Running the installer again would delete its database.
    Update the panel from its dashboard (Setup & Migration, New Updates).
    Take a backup with: xtreamgo backup
    To erase everything and install from scratch, run the installer again with --reinstall-wipe

Do not run the installer again to repair a panel. Use Troubleshooting.

What the installer creates

Path or object	Content
`/home/xtreamgo/docker-compose.yml`	Service definitions. Container logs are capped at 5 files of 50 MB for each service.
`/home/xtreamgo/.env.production`	Configuration and secrets. Mode 600.
`/home/xtreamgo/CREDENTIALS.txt`	Admin password, license key, database passwords. Mode 600.
`/home/xtreamgo/nginx/nginx.conf`, `/home/xtreamgo/nginx/conf.d/`	Web server configuration.
`/home/xtreamgo/ssl/`	Certificate files after `ssl-setup.sh`.
`/home/xtreamgo/scripts/`	`backup.sh`, `quality_check.sh`, `deploy_zero_downtime.sh`, `fast_rollback.sh`, `db_lb_access_sync.sh` and others.
`/home/xtreamgo/backups/`	Target of `xtreamgo backup`.
`/home/xtreamgo/data/`, `/home/xtreamgo/logs/`, `/home/xtreamgo/db/`	Created empty. The containers store their data in Docker volumes instead (`xtreamgo_db_data`, `xtreamgo_api_data`, `xtreamgo_api_logs`, `xtreamgo_api_backups`).
`/etc/systemd/system/xtreamgo.service`	Starts the stack at boot.
`/usr/local/bin/xtreamgo`	Management command.
`/etc/cron.d/xtreamgo-health`	Daily check at 06:17. Output in `/var/log/xtreamgo-health.log`.
`/etc/cron.d/xtreamgo-nginx-selfheal` and `xtreamgo-nginx-selfheal-daemon.service`	Reload nginx when the API container address changes.
`xtreamgo-db-access-sync.timer`	Every 20 seconds: keeps the database port closed to everyone except registered load balancers.

The `xtreamgo` command

The installer writes the management command to /usr/local/bin/xtreamgo. Without an argument it prints its usage text.

After the first panel update the API runs as xtreamgo-api-blue or xtreamgo-api-green and no longer as the Docker Compose service api. This is called blue/green mode: the panel keeps the previous API version stopped next to the new one so it can switch back. The command finds the running API container by itself.

Command	What it does
`xtreamgo status`	Lists the running containers with `xtreamgo` in their name: name, status and ports.
`xtreamgo health`	Prints the Docker health state of `xtreamgo-db`, `xtreamgo-redis`, the live API container, `xtreamgo-frontend`, `xtreamgo-portal`, `xtreamgo-website` and `xtreamgo-nginx`. A container that does not exist shows `missing`.
`xtreamgo logs`	Follows the logs of all Docker Compose services, starting with the last 50 lines.
`xtreamgo logs api`	Follows the log of the live API container, starting with the last 100 lines.
`xtreamgo logs <service>`	Follows the log of the container `xtreamgo-<service>`. Use `frontend`, `portal`, `website`, `nginx`, `db` or `redis`.
`xtreamgo shell`	Opens a shell inside the live API container.
`xtreamgo db`	Opens a MariaDB console on the panel database as root.
`xtreamgo backup`	Runs `/home/xtreamgo/scripts/backup.sh`. See Backup and restore.
`xtreamgo quality`	Runs the self-diagnostic `/home/xtreamgo/scripts/quality_check.sh`.
`xtreamgo restart <service>`	Runs `docker compose restart <service>`. The service names are those of `docker-compose.yml`: `db`, `api`, `frontend`, `portal`, `customer-website`, `redis`, `nginx`.
`xtreamgo restart api`	Before the first update: restarts the API. In blue/green mode: refused. See below.
`xtreamgo update <service>`	Runs `docker compose up -d --no-deps --force-recreate <service>` with the same service names.
`xtreamgo update api`	Before the first update: recreates the API container. In blue/green mode: refused. See below.
`xtreamgo deploy [image]`	Runs `/home/xtreamgo/scripts/deploy_zero_downtime.sh` with an API image that is already loaded on the server. The default is `xtreamgo-api:latest`.
`xtreamgo start`	Runs `docker compose up -d` for all services.
`xtreamgo stop`	Runs `docker compose down`.
`xtreamgo restart`	Runs `docker compose restart` for all services.
`xtreamgo update`	Runs `docker compose up -d --force-recreate` for all services.

xtreamgo update does not download a new version. It recreates containers from the images that are already on the server, with the settings from .env.production. The usage text of the command describes it as Rebuild and restart. It does not build or download anything. New versions arrive only through the Updates page. See Updates and rollback.

In blue/green mode xtreamgo restart api and xtreamgo update api change nothing, end with exit code 1 and print:

text

The API runs in blue/green mode (xtreamgo-api-green). Starting the compose api service would run two APIs.
Update it from the dashboard (Setup & Migration, New Updates). To restart it: docker restart xtreamgo-api-green

The container name in the message is the live one on your server. To restart the API in blue/green mode, use the docker restart command from the message. The restart interrupts the API for a short time.

In blue/green mode always use the forms with a service name. The refusal applies only to the forms with the argument api. xtreamgo start, xtreamgo restart and xtreamgo update without an argument act on every Docker Compose service, including the original api service. They can start the original container xtreamgo-api next to the live one. xtreamgo stop does not stop the live API container, because Docker Compose does not manage it. If two API containers run, see item 15 of Troubleshooting.

When quality_check.sh or deploy_zero_downtime.sh is missing, xtreamgo quality and xtreamgo deploy name the missing file, end with exit code 1 and print (This install is older than the script. Update the panel from the dashboard (Setup & Migration, New Updates), or ask support for the file.)

How to check it worked

bash

xtreamgo status
xtreamgo health
curl -s http://127.0.0.1/health
curl -s http://127.0.0.1/api/v1/build/info
curl -s http://127.0.0.1/api/v1/license/status

Expected results:

Seven containers with status Up, and healthy for each of the seven lines of xtreamgo health.
/health returns "status":"healthy".
/api/v1/build/info returns the version and "panel_mode":"client".
/api/v1/license/status returns "licensed":true.
The login page opens in the browser.

If something goes wrong

Message	Meaning	Action
`License key is required!`	The key prompt was left empty.	Start again and enter the key.
`Invalid or expired license key!`	The license server rejected the key. A second line shows the reason, for example `License key not found`, `License has expired`, `License is suspended` or `Hardware fingerprint required for this license`.	Check the key. For a fingerprint message, ask XtreamGo support to reset the fingerprint.
`Cannot reach license server. Check your internet connection.`	No answer from `api.xtreamgo.io`.	Check outbound HTTPS and DNS.
`Could not download SHA256SUMS from ...; refusing to install an unverified bundle`	The checksum list could not be downloaded.	Check the connection and start again. No container exists yet at this point.
`Bundle checksum mismatch (expected ..., got ...); refusing to install`	The image bundle is damaged or incomplete.	Start again. If it repeats, contact XtreamGo support.
`License activation issue, will auto-activate after services start`	The activation call did not return success. One cause is `License is already activated` on a reinstall.	Continue. Check the License page after login.
`Services started (some still initializing)`	The API was not healthy after 15 minutes.	See items 1 and 2 of Troubleshooting.
`WARNING: some containers did not start`	Fewer containers run than the compose file defines.	Run `xtreamgo status`. See item 1 of Troubleshooting.
`WARNING: database port 3306 is exposed to the internet and the guard could not be installed. Check immediately!`	Port 3306 listens on all interfaces and no firewall rule protects it.	Run `ss -ltn \| grep 3306` and `iptables -S DOCKER-USER`. Close the port in your provider firewall and contact XtreamGo support.
`An XtreamGo panel that is already in use was found on this server.`	The installer found a panel with data and stopped.	Nothing was changed. Read the section "Running the installer again". To update the panel, use the dashboard. To repair it, see Troubleshooting.

Install the main server

Before you start

Steps

1. Download the installer and the checksum list

2. Verify the checksum

3. Run the installer

4. Answer the questions

5. Wait for the six steps

6. Answer the two optional questions

7. Log in

8. Complete the first-run wizard

9. Change the admin password later

Unattended installation

Running the installer again

What the installer creates

The xtreamgo command

How to check it worked

If something goes wrong

The `xtreamgo` command