Getting Started

• Picking a Server OS

• Dependencies

  • Example Dependency Installation

  • Installing Composer

• Download Files

• Installation

  • Environment Configuration

  • Database Setup

  • Add The First User

  • Set Permissions

• Queue Listeners

  • Crontab Configuration

  • Create Queue Worker

  • Telemetry

Picking a Server OS

You can run on a wide range of operating systems, so pick whichever you are most comfortable using.

Kubectyl supports OpenVZ systems, but they are not highly recommended.

Operating System	Version	Supported	Notes
Ubuntu	18.04	Yes	Documentation written assuming Ubuntu 18.04 as the base OS.
	20.04	Yes
	22.04	Yes
	22.04	Yes	MariaDB can be installed without the repo setup script.
CentOS	7	Yes	Extra repos are required.
	8	Yes	Note that CentOS 8 is EOL. Use Rocky or Alma Linux.
Debian	10	Yes
	11	Yes

Dependencies

• PHP 8.0 or 8.1 (recommended) with the following extensions: cli, openssl, gd, mysql, PDO, mbstring, tokenizer, bcmath, xml or dom, curl, zip, and fpm if you are planning to use NGINX.

• MySQL 5.7.22 and higher (MySQL 8 recommended) or MariaDB 10.2 and higher.

• Redis (redis-server)

• A webserver (Apache, NGINX, Caddy, etc.)

• curl

• tar

• unzip

• git

• composer v2

Example Dependency Installation

The commands below are simply an example of how you might install these dependencies. Please consult with your operating system's package manager to determine the correct packages to install.

# Add "add-apt-repository" command
apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg

# Add additional repositories for PHP, Redis, and MariaDB
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php

# Add Redis official APT repository
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

# MariaDB repo setup script can be skipped on Ubuntu 22.04
curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash

# Update repositories list
apt update

# Add universe repository if you are on Ubuntu 18.04
apt-add-repository universe

# Install Dependencies
apt -y install php8.1 php8.1-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-server

Installing Composer

Composer is a dependency manager for PHP that allows us to ship everything you'll need code wise to operate the Panel. You'll need composer installed before continuing in this process.

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Download Files

The first step in this process is to create the folder where the panel will live and then move ourselves into that newly created folder. Below is an example of how to perform this operation.

mkdir -p /var/www/kubectyl
cd /var/www/kubectyl

Once you have created a new directory for the Panel and moved into it you'll need to download the Panel files. This is as simple as using curl to download our pre-packaged content. Once it is downloaded you'll need to unpack the archive and then set the correct permissions on the storage/ and bootstrap/cache/ directories. These directories allow us to store files as well as keep a speedy cache available to reduce load times.

curl -Lo panel.tar.gz https://github.com/kubectyl/panel/releases/download/v0.1.0-beta/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/

Installation

Now that all of the files have been downloaded we need to configure some core aspects of the Panel.

Database Configuration

You will need a database setup and a user with the correct permissions created for that database before continuing any further. See below to create a user and database for your Kubectyl panel quickly. To find more detailed information please have a look at Setting up MySQL.

mysql -u root -p

# Remember to change 'yourPassword' below to be a unique password
CREATE USER 'kubectyl'@'127.0.0.1' IDENTIFIED BY 'yourPassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'kubectyl'@'127.0.0.1' WITH GRANT OPTION;
exit

First we will copy over our default environment settings file, install core dependencies, and then generate a new application encryption key.

cp .env.example .env
composer install --no-dev --optimize-autoloader

# Only run the command below if you are installing this Panel for
# the first time and do not have any Kubectyl Panel data in the database.
php artisan key:generate --force

DANGER

Back up your encryption key (APP_KEY in the file). It is used as an encryption key for all data that needs to be stored securely (e.g. api keys). Store it somewhere safe - not just on your server. If you lose it all encrypted data is irrecoverable -- even if you have database backups.

Environment Configuration

Kubectyl's core environment is easily configured using a few different CLI commands built into the app. This step will cover setting up things such as sessions, caching, database credentials, and email sending.

php artisan p:environment:setup
php artisan p:environment:database

# To use PHP's internal mail sending (not recommended), select "mail". To use a
# custom SMTP server, select "smtp".
php artisan p:environment:mail

Database Setup

Now we need to setup all of the base data for the Panel in the database you created earlier. The command below may take some time to run depending on your machine. Please DO NOT exit the process until it is completed! This command will setup the database tables and then add all of the Nests & Eggs that power Kubectyl.

php artisan migrate --seed --force

Add The First User

You'll then need to create an administrative user so that you can log into the panel. To do so, run the command below. At this time passwords must meet the following requirements: 8 characters, mixed case, at least one number.

php artisan p:user:make

Set Permissions

The last step in the installation process is to set the correct permissions on the Panel files so that the webserver can use them correctly.

# If using NGINX or Apache (not on CentOS):
chown -R www-data:www-data /var/www/kubectyl/*

# If using NGINX on CentOS:
chown -R nginx:nginx /var/www/kubectyl/*

# If using Apache on CentOS
chown -R apache:apache /var/www/kubectyl/*

Queue Listeners

We make use of queues to make the application faster and handle sending emails and other actions in the background. You will need to setup the queue worker for these actions to be processed.

Crontab Configuration

The first thing we need to do is create a new cronjob that runs every minute to process specific Kubectyl tasks, such as session cleanup and sending scheduled tasks to daemons. You'll want to open your crontab using sudo crontab -e and then paste the line below.

* * * * * php /var/www/kubectyl/artisan schedule:run >> /dev/null 2>&1

Create Queue Worker

Next you need to create a new systemd worker to keep our queue process running in the background. This queue is responsible for sending emails and handling many other background tasks for Kubectyl.

Create a file called kubeq.service in /etc/systemd/system with the contents below.

# Kubectyl Queue Worker File
# ----------------------------------

[Unit]
Description=Kubectyl Queue Worker
After=redis-server.service

[Service]
# On some systems the user and group might be different.
# Some systems use `apache` or `nginx` as the user and group.
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/kubectyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s

[Install]
WantedBy=multi-user.target

Redis on CentOS

If you are using CentOS, you will need to replace with at the line in order to ensure starts before the queue worker.

TIP

If you are not using for anything you should remove the line, otherwise you will encounter errors when the service starts.

If you are using redis for your system, you will want to make sure to enable that it will start on boot. You can do that by running the following command:

sudo systemctl enable --now redis-server

Finally, enable the service and set it to boot on machine start.

sudo systemctl enable --now kubeq.service

Telemetry

Since 1.11, Kubectyl will collect anonymous telemetry to help us better understand how the software is being used. To learn more about this feature and to opt-out, please see our Telemetry documentation. Make sure to continue with the rest of the installation process.