Skip to content

CyTube 3.0 Installation Guide

AlexandriaOL edited this page Jan 12, 2021 · 54 revisions

This guide will walk you through installing and configuring CyTube on a Linux server.

Table of Contents

  1. Requirements
  2. Installation of prerequisites
  3. Installation of CyTube 3.0
  4. Configuration
  5. Running
  6. Maintenance
  7. Appendix A: Example config using nginx with SSL
  8. Appendix B: Example config using Caddy as a reverse proxy


The current installation and configuration procedures are not beginner-friendly. I wish it were, but as of today, it is what it is. If you don't have knowledge/experience in the following areas, you are likely to have a difficult time installing and operating this server software:

  • Linux system administration
  • Webserver administration
  • Web development
  • Database administration
  • Basic debugging skills

Please note that IRC can only provide support for CyTube itself and does not provide assistance with configuring Linux, MySQL, webservers, etc.


Requirements listed are for the server. The website itself is compatible with most modern browsers (older devices, such as mobile phones and game consoles, may have compatibility issues).

Operating System

OS Supported Notes
Linux (64-bit/amd64) Yes Older distributions (e.g. Ubuntu 12.04) may have compatibility issues with newer versions of the code.
Linux (32-bit/x86) ? I don't own an x86 machine anymore and don't test on this architecture. Some dependencies with C++ bindings may not work.
OS X/macOS Unofficially
FreeBSD Unofficially It has been a while since I tested this
Solaris Unofficially I only know of one person who submitted a patch for Solaris compatibility; I've never tried it myself
Windows No People have submitted reports of incompatibility in the past. I don't currently have plans to investigate this.

If you would like to report a compatibility issue or a known-working operating system that is not listed here, feel free to edit this wiki page and/or open an issue.

This guide assumes you have full root access to the machine; I don't support SaaS providers such as Heroku or OpenShift (feel free to open an issue/PR if you find a way to make it work -- see for previous discussion).

System Requirements

CyTube is relatively lightweight in terms of CPU, memory, and bandwidth usage. For a small instance, you can host a reverse proxy such as nginx, the MySQL/MariaDB database, and CyTube's node.js process within 512MB of RAM (for example, a t2.nano instance from EC2). However, such small amounts of RAM may require workarounds for npm install (more details below).

Software Requirements

  • MySQL/MariaDB must be at least version 5.5.3 for compatibility with the utf8mb4 character set.
  • The current Active LTS of node.js is recommended. The bleeding edge (latest version) may not be supported yet, and support for older versions is frequently dropped to take advantage of newer features. You can check the version by running node -v
  • CyTube will require its own non-root user to run as. Running as root is not supported. New users can easily be added on linux with useradd (refer to your distribution's documentation as needed)
  • (Optional) nginx for reverse proxying web content. Setup is outside the scope of this guide.

Installation of prerequisites


Debian / Ubuntu

sudo apt update && sudo apt upgrade
sudo apt install build-essential git mariadb-server

Refer to to install node.js


  • The CentOS instructions were contributed by a user many years ago and haven't been tested recently. Feel free to update the wiki if changes are needed.
yum update
yum install git openssl-devel gcc-c++ mysql-server mysql mysql-devel mysql-libs

Refer to to install node.js

Installation of CyTube 3.0

Cloning from git

cd to the directory where you want your CyTube server. Execute the following command to download the code from the Git repository:

git clone -b 3.0

You can optionally specify a folder name after the repository URL to rename the folder something else instead of sync.

NPM dependencies

DO NOT RUN NPM AS ROOT. npm does not run pre/postinstall scripts when executed as root, for safety reasons, but logs a warning instead of failing. This causes the installation to be incomplete, and the software won't work correctly.

Even if you plan to use the setuid feature to run as root and drop privileges, the software should be installed as a non-root user.

cd sync
if [ "$(whoami)" = "root" ]; then
  echo "Do not run this as root!"
  npm install

npm performance

CyTube has a lot of dependencies due to the nature of node's ecosystem, and some of them bring in very large dependency trees (for example, babel) or require compilation of C++ bindings. On systems with <1GB of available memory, the installation process may run out of memory and fail. In this case, you are better off running npm install on a similar system with more memory and copying the node_modules folder to the server with less memory (then running npm run postinstall to perform the final build step).



You will need to log in to your MySQL server as root to create a user and database for CyTube:

mysql -u root -p
GRANT USAGE ON *.* TO cytube3@localhost IDENTIFIED BY 'super_secure_password';
GRANT ALL PRIVILEGES ON cytube3.* TO cytube3@localhost;

Note for MySQL users

If you are using MySQL (not the MariaDB fork), you may run into issues with CyTube's use of DEFAULT 0 for certain timestamp columns, resulting in this error: Error: ER_INVALID_DEFAULT: Invalid default value for 'last_loaded'. This is because MySQL defaults to setting SQL mode NO_ZERO_DATE, which is deprecated. You can fix it by running the following command as the MySQL root user:

SET GLOBAL sql_mode = replace(@@global.sql_mode, 'NO_ZERO_DATE,', '');

Configuration File

NOTE: The configuration file is somewhat confusing and messy. This is a known issue that I'm planning to work on.

First, copy the template:

cp config.template.yaml config.yaml

Next, edit config.yaml with your favorite text editor. The template is well-commented with what most of the config keys are for, so I will omit explaining all of them in detail, but I would like to make a few general notes:

  • http.root-domain has to do with the way cookies work. If your server will be accessible from multiple subdomains (e.g.,, then you must set the root domain to the common domain between them (e.g.
  • As a convention, keys called host specify an IP address to bind to (if your server has multiple IP addresses), and keys called domain specify the domain name (e.g.
  • Binding a port number below 1000 requires running the server as root. This is one of the reasons I use nginx as a reverse proxy.


Congratulations, your CyTube server is now configured! You can launch it with node index.js. Note that the server runs in the foreground; you will probably see a few initialization messages and then the process will keep running (waiting for users to connect). On the first run, your server will initialize the database, log files, and channel data folders. You should be able to connect to your server on the port specified.

Once you have registered your first account, you can use the following commands to assign yourself site admin rights:

mysql -u cytube3 -p cytube3
UPDATE `users` SET global_rank=255 WHERE name='calzoneman';

Any rank >= 255 has site administrator permissions.


There are a few options for keeping the server running after you close your SSH session:

  • nohup node index.js &
  • screen
  • tmux
  • upstart
  • forever

nohup, screen, and tmux are all available as packages on major distributions. Forever comes with npm. upstart is available on Ubuntu 6.10 and later. I have also provided a simple script that will automatically restart the server if it crashes. On my server, I launch it as screen ./

Forever setup

Install forever with this command:

sudo npm install -g forever

And then start cytube with:

forever index.js

Or as a service:

forever start index.js

Forever restarts your app when it crashes or stops for some reason. To restrict restarts to 5 you could use:

forever -m5 index.js

To list all running processes:

forever list

Note the integer in the brackets and use it as following to stop a process:

forever stop 0

Restarting a running process goes:

forever restart 0

Upstart Example

First, create the configuration file. The example below assumes you've cloned the repo to /home/ubuntu/sync. Change this directory as necessary.

cat > /etc/init/cytube.conf << EOF
description "CyTube"

start on (filesystem and net-device-up)
stop on runlevel [!2345]

setuid ubuntu

respawn limit 2 60

chdir /home/ubuntu/sync

  exec /home/ubuntu/sync/
end script

emits CyTube-running 

Next, start the service using upstart:

sudo service cytube start


Git updates

CyTube is actively developed and updates frequently to fix bugs and add new features. Git provides a convenient way for you to keep up with these updates. cd to the directory containing CyTube, and execute git pull to retrieve the latest code. As of September 2015, you must also run npm install, npm run postinstall, or npm run build-server to build the changes from src/ to lib/. After this, restart the server for the changes to take effect.


You should take frequent backups in case something happens to your server. The database and channel data can be backed up like so:

mysqldump --quick --skip-lock-tables -u cytube -psupersecretpassword cytube > my_database_backup.sql
tar cjf my_channels_backup.tar.bz2 chandump

Appendix A: Example config using nginx with SSL

This example configuration shows how to set up nginx as a reverse proxy for CyTube's webserver and enable SSL. Note that the reverse proxy only proxies HTTP requests; websockets connect directly through the https port configured in CyTube's config.yaml.

# /etc/nginx/sites-available/cytube
server {
        listen 443 ssl;

        ssl_prefer_server_ciphers on;
        ssl_certificate /etc/letsencrypt/live/;
        ssl_certificate_key /etc/letsencrypt/live/;

        location ~ .* {
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header Host $http_host;
# config.yaml
  - ip: ''
    port: 8080
    http: true
  - ip: ''
    port: 8443
    https: true
    io: true

  root-domain: ''

  enabled: true
  default-port: 8443
  domain: ''
  keyfile: 'privkey.pem'
  passphrase: ''
  certfile: 'fullchain.pem'
  cafile: ''
  ciphers: 'HIGH:!DSS:!aNULL@STRENGTH'

Appendix B: Example config using Caddy as a reverse proxy

This example configuration shows how to set up Caddy as a reverse proxy for CyTube's webserver and enable SSL. Note that the reverse proxy only proxies HTTP requests; websockets are passed through and connect directly through the https port configured in CyTube's config.yaml.

In this example we are binding CyTube's HTTP server to 1234, and CyTube's HTTPS websocket server to 8443.

This requires some setup, you will need to create a new group for the Caddy credentials, and give Cytube access to that group. You then need to change read/write permissions and group permissions on both the SSL credentials, and all higher folders in the file tree (up to /home). If you do not do this step, you get the error that it cannot load, visiting that page in Firefox will give you a SSL_ERROR_RX_RECORD_TOO_LONG error, and trying to curl it will give you a TLSv1.3 version error.

The result should look like this (where sitecerts is our newly made group):

root@host:/home/caddy$ ls -lh /home/caddy/.local/share/caddy/certificates/
-rw-r----- 1 caddy sitecerts 3141 Jan  8 23:54
-rw------- 1 caddy caddy      149 Jan  8 23:54
-rw-r----- 1 caddy sitecerts  227 Jan  8 23:54

The location of Caddy's certificate files is /home/caddy/.local/share/caddy/certificates/ Usually you will have to change group and group read permissions up to (but not including) /home/.

Caddy's config is rather simple, and it's sufficient only to add in a single block in /etc/caddy/Caddyfile.

# /etc/caddy/Caddyfile {
        reverse_proxy localhost:1234

And then finally in your config.yaml you will want to have:

# config.yaml
  - ip: ''
    port: 8080
    http: true
  - ip: ''
    port: 8443
    https: true
    io: true

  root-domain: ''

  enabled: true
  default-port: 8443
  domain: ''
  keyfile: '/path/to/your/certificate/file/'
  passphrase: ''
  certfile: '/path/to/your/certificate/file/'
  cafile: ''
  ciphers: 'HIGH:!DSS:!aNULL@STRENGTH'