Install VorqulPanel on a Linux server

Requirements

Install

Part 1: Prepare the server#

A clean server is a real requirement and more than a recommendation. The panel manages nginx, Apache, BIND9, Postfix, Dovecot, MariaDB and nftables, and it is far easier on a machine where it installed them itself.

1. Step 01

   Start from a supported distribution#

   Debian 12, Ubuntu 22.04 or newer, or AlmaLinux 9, freshly provisioned, with root access over SSH.

   Installing onto a server that already runs someone else's web stack is possible. The installer does not offer to reinstall a web server, PHP-FPM, MariaDB, certbot, BIND, Postfix or fail2ban that is already there, and the panel reads existing vhosts without rewriting them until you confirm a takeover. It is still not the install to do first.

2. Step 02

   Java comes with the installer#

   The panel is a single JAR and needs Java 25 or newer. The installer installs it when it is missing, so there is nothing to do here unless you want to check first.

   java -version

3. Step 03

   Sort out SSH access before the firewall exists#

   Know which port your SSH daemon listens on, and make sure you can get back in. The firewall comes later and it will need an explicit rule for it.

   Non-standard SSH port plus a default firewall rule set is the classic way to lock yourself out of a fresh panel install.

Install

Part 2: Install the panel#

One script does the whole installation. There is nothing to compile.

1. Step 04

   Copy the folder to the server#

   The release is one folder with the JAR, a scripts directory and the systemd unit templates. Put it somewhere permanent such as /root/vorqul-panel.

   Keep the folder after installing. vorqulctl fix-libs and later updates use it. The libraries in lib/ are downloaded by the installer from Maven Central with checksum verification, so they do not need to be copied.

   VorqulPanel is in alpha and is not handed out for testing by email yet. When a build is shared with you, the archive comes with the exact commands for that version. The steps here describe what those commands do.

   • vorqul-panel.jar is the panel itself
   • scripts/install.sh is the installer and is required
   • scripts/vorqul-helper is the root helper for firewall ports, resource limits and services
   • scripts/vorqulctl is the command-line tool
   • scripts/vorqul-doctor.sh is an optional diagnostics script
   • systemd/ holds service templates, optional because the installer has its own copy
2. Step 05

   Run the installer as root#

   It asks which parts you want, installs what is missing, creates the service user and prints the one-time setup URL.

   • Asks which modules to enable: game hosting, web hosting, mail
   • Asks which packages to install: nginx or Apache, PHP-FPM, MariaDB, certbot, BIND, Postfix with Dovecot, Rspamd, game tools, fail2ban
   • Installs Java if it is missing and creates the vorqul system user
   • Copies the JAR to /opt/vorqul-panel, writes a config with a random secret and sets up the systemd services
   • Opens the ports in ufw or firewalld and prints the setup URL

   sudo bash scripts/install.sh

   The installer looks for the JAR in target/, next to the repository root or next to the script, so run it from the unpacked folder.

3. Step 06

   Unattended install and variables#

   Every question has an environment variable. With YES=1 nothing is asked and the variables, or the defaults, are used.

   • INSTAL_DIR (default /opt/vorqul-panel), DATA_DIR and LOG_DIR set where the JAR, the data and the logs live
   • SYSTEM_USER (default vorqul) is the user the panel runs as
   • PORT, SFTP_PORT and SFTP_DAEMON_PORT default to 8765, 8766 and 8767
   • MOD_GAMES, MOD_WEB and MOD_MAIL default to 1 and switch the three parts of the panel
   • WEB_SERVER is nginx, apache or none and only applies with MOD_WEB=1
   • INSTALL_PHP, INSTALL_MARIADB, INSTALL_CERTBOT, INSTALL_BIND, INSTALL_MAIL, INSTALL_RSPAMD, INSTALL_FAIL2BAN and INSTALL_GAMETOOLS pick packages
   • DB_ENGINE is sqlite by default, with mysql, postgres and mssql as options and DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS for the connection
   • WEB_ADMIN=1 installs the root helper and a narrow sudoers file, USE_EXISTING=0 lets the installer touch software that is already installed

   sudo YES=1 MOD_MAIL=0 WEB_SERVER=nginx INSTALL_PHP=1 INSTALL_MARIADB=1 INSTALL_CERTBOT=1 bash scripts/install.sh

   SQL Server support is beta. SQLite, MySQL, MariaDB and PostgreSQL have been checked against real servers. Changing db.engine later does not move any data.

4. Step 07

   Confirm the service is up#

   The panel runs as a hardened systemd service called vorqul-panel. Check that it started, and read the journal if it did not.

   sudo systemctl status vorqul-panel
   sudo vorqulctl status
   sudo vorqulctl logs err

   If package installs fail during setup, the usual cause is RestrictSUIDSGID=yes in the unit breaking post-install scripts.

5. Step 08

   Open the ports#

   The installer opens 8765, 8766 and 8767 in ufw or firewalld. With plain nftables it asks first and inserts one rule that does not survive a reboot.

   With plain nftables, also add tcp dport { 8765, 8766, 8767 } accept to /etc/nftables.conf. Behind a reverse proxy only 80 and 443 need to be public and 8765 should stay closed to the internet.

   • Panel 8765, embedded SFTP 8766, SFTP daemon 8767, all tcp
   • Websites 80 and 443, mail 25, 587, 465, 143, 993 and 4190, DNS 53 on tcp and udp
   • Each game server opens its own port when it is created, and Hytale uses UDP 5520

Install

Part 3: First login and setup#

From here everything happens in the browser.

1. Step 09

   Open the setup link#

   Go to http://your-server:8765/. Until an admin exists it opens the setup form, and the full link comes from the installer or from the command below.

   sudo vorqulctl setup-url

   Whoever reaches the port first can create the admin. That window closes an hour after the panel starts, and after that the setup link is needed.

2. Step 10

   Create the admin account and turn on 2FA#

   Create the first account immediately, then enable two-factor authentication under Settings, Account. Two-factor can be made mandatory for admins.

   If you ever lose the admin account, run sudo vorqulctl reset-admin and then sudo vorqulctl start. It prints a fresh setup link where you create a new admin.

3. Step 11

   Enter the license key#

   Until a valid key is verified the panel stays locked and sends you to the License page. Open /license, enter the key and the domain it was issued for, and press Activate.

   When the web page is not reachable, put the same two values into /opt/vorqul-panel/vorqul-panel.conf as license.key and license.domain, then restart the service. The server needs outbound HTTPS to reach the license server.

   license.domain must be the domain the key was issued for. There is no license file to create by hand because data/license.json only caches the server's signed answer.

4. Step 12

   Check the module switches#

   Settings has Game hosting, Web hosting and Mail tabs. Turn off what this machine does not do. A switch that is off hides the page and also makes its API answer 404.

   Nothing is uninstalled and no data is deleted by switching a part off. Services, Manual setup lists what is installed and what is missing, with an Install button for each item.

5. Step 13

   Add your first domain#

   Point an A record at the server first, then add the domain in the panel, press Apply to write the vhost and press HTTPS once DNS resolves here.

   Certificates come from acme.sh or certbot and both need the DNS record resolving before they will issue. If the record was only just changed, wait for propagation rather than retrying in a loop.

   A certificate issued but the site still serving plain HTTP usually means an adopted vhost that has not had its takeover confirmed yet.

6. Step 14

   Run the config test#

   Every Apply runs the web server config test with automatic rollback. Run it once deliberately, so you have seen what a passing result looks like.

   That rollback is the reason a bad vhost does not take the whole server down. The panel tests the new configuration before reloading and puts the old one back if the test fails.

Commands

Part 4: Commands#

Everything you type on the server. Run vorqulctl as root or with sudo.

1. Step 15

   systemd service commands#

   The panel is the vorqul-panel service and the standalone SFTP daemon is vorqul-sftp.

   sudo systemctl status vorqul-panel
   sudo systemctl restart vorqul-panel
   sudo systemctl stop vorqul-panel
   sudo systemctl enable vorqul-panel
   sudo journalctl -u vorqul-panel -n 100 --no-pager

2. Step 16

   vorqulctl: day to day#

   The short commands you will use most.

   • vorqulctl status shows service state, port and version
   • vorqulctl start, stop and restart control the service
   • vorqulctl enable and disable decide whether it starts on boot
   • vorqulctl logs [tail|follow|err|all] reads the panel log, last 100 lines by default
   • vorqulctl info prints paths, ports and the data directory
   • vorqulctl version prints the panel version
3. Step 17

   vorqulctl: setup and recovery#

   For the first login, a lost admin or a quick copy of the configuration.

   • vorqulctl setup-url prints the first-run setup link again
   • vorqulctl reset-admin creates a new setup URL for a fresh admin account and turns password sign-in back on
   • vorqulctl config opens the config file in an editor
   • vorqulctl backup writes a tar.gz of the config and data directory into /tmp
4. Step 18

   vorqulctl: maintenance#

   Modules, runtimes, libraries, updates and removal.

   • vorqulctl modules [games|web|mail on|off] shows or switches a module together with its host rights
   • vorqulctl deps <runtime> installs runtimes such as node20, java25 or steamcmd
   • vorqulctl fix-libs downloads the libraries in lib/ again
   • vorqulctl fix-priv reinstalls the sudoers file, the root helper and the systemd override
   • vorqulctl update <jar> installs a new JAR with backup, atomic swap, restart, health check and automatic rollback
   • vorqulctl uninstall [--purge-data] removes the panel and keeps the data unless you purge it

   sudo vorqulctl modules mail on
   sudo vorqulctl update /path/to/vorqul-panel.jar

5. Step 19

   The root helper#

   The panel runs as an unprivileged user. Anything that needs root goes through vorqul-helper, which accepts a fixed list of actions and nothing else.

   The helper reads /etc/vorqul-helper.conf, which is root-owned and written by the installer. It is cut down to the modules you picked, so switching a module on in Settings alone does not give the panel those rights. The panel shows a banner with the command, and sudo vorqulctl modules <name> on is that command.

   Whatever the modules, the panel never stops SSH, nftables, ufw, firewalld or cron, never flushes the firewall or changes its default policy, only adds and removes its own tagged rules, and never bans anything in fail2ban on its own.

6. Step 20

   Diagnostics#

   When a server will not start and the log is empty, run the doctor. It talks to nothing, changes nothing and runs each game server command by hand so you see the real error.

   /healthz returns JSON with version, uptime, database status and the number of running servers, which makes it a good target for your own monitoring.

   ./scripts/vorqul-doctor.sh /opt/vorqul-panel
   curl -s http://127.0.0.1:8765/healthz

Reference

Part 5: Paths and ports#

Where things live after a default install.

1. Step 21

   Files and directories#

   Everything the panel owns sits under /opt/vorqul-panel unless you changed INSTAL_DIR or DATA_DIR.

   • /opt/vorqul-panel holds the JAR, lib/ and vorqul-panel.conf
   • /opt/vorqul-panel/data holds the database, game servers and backups
   • /opt/vorqul-panel/logs holds vorqul-panel.log
   • /etc/systemd/system/vorqul-panel.service and vorqul-sftp.service are the units
   • /usr/local/bin/vorqulctl is the command-line tool
   • /usr/local/sbin/vorqul-helper and /etc/vorqul-helper.conf are the root helper and its policy
   • /etc/sudoers.d/vorqul-panel is the narrow sudoers file
2. Step 22

   Default ports#

   The first three belong to the panel. The rest depend on which parts you use.

   • 8765 tcp is the web interface and API
   • 8766 tcp is the embedded SFTP and 8767 tcp is the standalone SFTP daemon
   • 80 and 443 tcp for websites and certificates
   • 25, 587, 465, 143, 993 and 4190 tcp for mail
   • 53 tcp and udp for DNS
   • Each game server uses its own port

Reference

Part 6: Configuration file#

The file is /opt/vorqul-panel/vorqul-panel.conf with one key = value per line. Almost everything is also a switch in Settings, so you rarely need to edit it by hand. Restart the service after changing it.

1. Step 23

   Server, database and security#

   The keys that decide how the panel listens and where it keeps its data.

   • server.host and server.port set the listen address and port
   • server.public.url is the address people open, needed for sign-in with Google or Discord
   • server.tls.keystore points at a PKCS12 keystore for direct HTTPS
   • data.dir is the data directory
   • db.engine is sqlite, mysql, postgres or mssql, with a db.<engine>.host, port, database, user and password block for the one in use
   • security.secret signs sessions and is generated by the installer, so do not change it casually
   • panel.trust.proxies lists the only peers allowed to set forwarding headers
   • cloudflare.mode makes the panel trust CF-Connecting-IP from Cloudflare ranges only
2. Step 24

   Feature switches#

   feature.games, feature.webhosting and feature.mail are the master switches. Each has child switches, and a child is only on while its parent is on.

   • Web: feature.domains, ssl, dns, databases, cache, webconfigs, webfiles, subdomains, websftp, webapps, webstats
   • Mail: feature.mail.dkim, antispam, tls, rules, catchall, autoconfig, delivery, webmail, dnsrecipe
   • Website tools: webcron, webbackup, webgit, webruntime
   • terminal.enabled turns on the browser terminal, off by default and only for admins with 2FA
3. Step 25

   Game servers and limits#

   How the panel treats running servers.

   • servers.keepRunning, servers.nice and servers.oomAdjust tune how servers survive and how they are scheduled
   • limits.cgroups turns on cgroup v2 limits, with limits.memory.headroomPercent defaulting to 125 and limits.pids.max off by default
   • limits.servers.maxRunning caps how many servers run at once
   • process.stop.timeout is how many seconds a server gets to save on stop, 30 by default and 150 at most
4. Step 26

   Backups and logging#

   Schedules and retention for the panel, offsite copies and website backups.

   • backup.panel.cron and backup.panel.retention schedule the panel backup and decide how many to keep
   • backup.offsite.* describes where encrypted copies are pushed
   • web.backup.keep is how many website backups are kept, 7 by default
   • log.level sets how much the panel writes to its log

   Run the doctor or read vorqulctl logs err when a change does not seem to apply. A typo in the file is the usual reason.

Features

Part 7: What the panel can do#

A short map of the interface, so you know where to look.

1. Step 27

   The sidebar menu#

   The menu is grouped by what it manages. The Web hosting, Mail and Game hosting groups can each be switched off in Settings.

   • Overview is the dashboard with system stats
   • Web hosting: Websites overview, Domains and sites, DNS zones, Databases, Cache, SSL certificates, Web server configs
   • Mail: Mail and Mail delivery
   • Game hosting: Game overview, Game servers, Scheduler, Backups
   • System, for admins only: Services, Nginx, Logs, Cron, Monitoring, Firewall, Security, Fail2ban, Tools, Webhooks, Users, Audit log, and Terminal (off by default)
   • Account: Settings, and Licence for admins
   • Users who are not admins also get My websites when they have access to any site
2. Step 28

   Game hosting#

   More than 240 templates with one-click install, a live console, files, backups, schedules and per-server SFTP.

   • Minecraft, Hytale, the Source family, Rust, Valheim, ARK, Palworld, FiveM, Discord bots, voice servers and a section for local AI tools
   • Crash analysis names the cause and the fix, for example a wrong Java version or an out-of-memory kill
   • Resource limits per server through cgroup v2 instead of nice or cpulimit
   • Per-user permissions from View to a Custom list such as console, power, files and backups
   • One-click install and update, a live console with command input and a file manager with editing, upload, zip and tar extraction and chmod
   • Manual and scheduled backups, a scheduler for restarts, backups and commands, and a chrooted SFTP account for each server
3. Step 29

   Web hosting#

   nginx or Apache vhosts, Let's Encrypt, DNS, databases and per-site tools.

   • Domains for nginx or Apache with free Let's Encrypt HTTPS, subdomains with certificate coverage shown, reverse-proxy mode and import of existing sites
   • BIND9 zones validated before reload and sync with Cloudflare
   • MariaDB databases and users with import, export and Adminer, plus suggestions for speeding a database up
   • PHP versions, pools and modules
   • Per-site tools: PHP settings, password protection, IP block, cron, backups, git deploy and Node.js or Python apps
   • Nginx settings for the whole server and for each site
   • Files, FTP and SFTP accounts per site, and one-click Roundcube and phpMyAdmin installers
   • Redis, Valkey and memcached from one page
4. Step 30

   Mail#

   Postfix and Dovecot with DKIM, a deliverability checker, queue, delivery log, blocklist checks and Roundcube.

   Add the domain, generate the DKIM key and publish the DNS records the panel shows. Check that the PTR record of your IP matches the mail hostname, because that is set where the IP is rented and no panel can change it.

   • Postfix, Dovecot and Rspamd installed with one button
   • Mailboxes, aliases, catch-all, forwarding and out-of-office replies
   • DKIM, SPF and DMARC, a deliverability checker, the mail queue, the delivery log and a blocklist check
   • A TLS certificate in one click, DNS record export and publishing to Cloudflare
   • Auto-configuration for Thunderbird, Outlook and Apple devices
5. Step 31

   Server, monitoring and security#

   Service control, watchers with self-healing, a public status page, alerts, firewall, malware scanning, roles and an audit log.

   • Install, start, stop and read logs of nginx, Apache, MariaDB, PHP-FPM and fail2ban, plus a log viewer, log cleaning and a cron editor
   • HTTP, TCP, ping, SSL-expiry, disk, memory, CPU and service monitors with self-healing, 30 days of history and a public status page at /status
   • Webhooks, Discord embeds and e-mail alerts on crashes, backups, low disk and expiring certificates
   • Firewall with ufw, firewalld or nftables, an optional base firewall that rolls back automatically, and a fail2ban setup wizard
   • Cloudflare real-IP update, and a browser terminal for admins with 2FA only
   • Three roles, Admin, Operator and Viewer, with per-server permissions of View, Control, Manage or Custom
   • TOTP two-factor, sign-in with Google or Discord, login lockout, CSRF protection, active-session management and an audit log with CSV export
   • Malware scanning with ClamAV, LMD, rkhunter and chkrootkit, and packages with user quotas

Backups

Part 8: Backups and offsite copies#

Set these up on the first day. Three kinds exist and each has its own place in the interface.

1. Step 32

   What gets backed up#

   Panel backups, game server backups and website backups are separate.

   On a schedule the panel also unpacks its own newest backup and opens the database inside it, which proves the archive can be restored and not just that it exists.

   • Panel backup covers the config, the database and the host configs it manages, on a cron schedule with retention
   • Game server backups are manual or scheduled, verified after writing, with restore from the UI and downloadable ZIPs
   • Website backups are one ZIP with the files and optionally the database, and can be uploaded to another Vorqul server to move a site
2. Step 33

   Push copies off the machine#

   Backups, Offsite targets. Copies are encrypted with AES-256-GCM before they leave the server.

   To read an encrypted copy yourself, use the decrypt-backup command of the JAR.

   • Direct targets: SSH, SFTP, FTP and S3
   • Google Drive, OneDrive and Dropbox through rclone

   java -jar vorqul-panel.jar decrypt-backup backup.zip.enc backup.zip

3. Step 34

   Google Drive and other clouds with rclone#

   Install rclone, create a remote once, then use that remote as an offsite target.

   In rclone config create a remote named gdrive of type drive. On a server without a browser answer no to the automatic configuration question and run rclone authorize "drive" on your own computer, then paste the token it prints. The lsd line should list your Drive folders before you point the panel at it.

   sudo apt install rclone
   rclone config
   rclone lsd gdrive:

4. Step 35

   Restoring#

   Game servers and websites restore from the interface. The panel database restores by hand with the panel stopped.

   The panel prints the exact command rather than replacing a database it is holding open. Restoring host configs works per file and keeps a .vorqul-pre-restore copy of whatever it replaces.

Maintenance

Part 9: Updating and uninstalling#

Configuration, database and game servers are never touched by an update.

1. Step 36

   Update just the JAR#

   The safe route. It saves the current JAR and config, swaps atomically, restarts, waits for /healthz and rolls back if the new version does not come up.

   sudo vorqulctl update /path/to/vorqul-panel.jar
   sudo vorqulctl fix-libs

   Run fix-libs afterwards only when the new version needs new libraries.

2. Step 37

   Update from the folder#

   Running the installer again recognises the existing install, keeps the config and refreshes lib/, the units and the helper.

   Replaced files are saved under the data directory in backups/_install/ and the last 10 runs are kept.

   Running game servers get their own stop command and process.stop.timeout seconds to save, then SIGTERM and finally SIGKILL. They start again when the panel comes back, and a planned restart is not reported as a crash.

   sudo bash scripts/install.sh

3. Step 38

   Uninstall#

   The first command removes the services, helper and sudoers rules and keeps your data. The second also deletes the data directory and the vorqul user after you type DELETE.

   sudo vorqulctl uninstall
   sudo vorqulctl uninstall --purge-data

   Packages the panel installed, websites under /var/www, mailboxes and firewall rules stay where they are.

Troubleshooting

The failures that actually happen, and what causes them.

Questions about installing

Summary

Installing VorqulPanel takes roughly 15 to 30 minutes on a clean Linux server. It needs Debian 12, Ubuntu 22.04 or newer, or AlmaLinux 9, with root access and at least 2 GB of RAM. The panel ships as a single JAR with scripts/install.sh, which installs Java 25 if it is missing, creates the service user, registers the vorqul-panel systemd unit and opens ports 8765 to 8767. There is no build step, no container runtime and no external database. The panel keeps its own state in SQLite by default.

• Time: 15 to 30 minutes
• Runtime: Java 25 or newer, installed for you
• Distributions: Debian 12, Ubuntu 22.04+, AlmaLinux 9
• Panel storage: SQLite, no external DB

Server control panel Self-hosted One-off license Audit log vorqulctl Root helper Setup URL Panel database Module switch Vhost takeover Offsite backup Two-factor authentication

Reviewed 2026-10-15