CyTube 3.0 Installation Guide

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

Disclaimer

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

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 https://github.com/calzoneman/sync/issues/550 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

Dependencies

Debian / Ubuntu

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

Refer to https://github.com/nodesource/distributions/blob/master/README.md to install node.js

CentOS

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 https://github.com/nodesource/distributions/blob/master/README.md 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 https://github.com/calzoneman/sync

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!"
else
  npm install
fi

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).

Configuration

Database

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

mysql -u root -p
# ENTER PASSWORD

GRANT USAGE ON *.* TO cytube3@localhost IDENTIFIED BY 'super_secure_password';
GRANT ALL PRIVILEGES ON cytube3.* TO cytube3@localhost;
CREATE DATABASE cytube3;
QUIT;

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. a.mysite.com, b.mysite.com), then you must set the root domain to the common domain between them (e.g. mysite.com).
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. mysite.com).
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.

Running

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
# ENTER PASSWORD

UPDATE `users` SET global_rank=255 WHERE name='calzoneman';

Any rank >= 255 has site administrator permissions.

Persistence

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 run.sh script that will automatically restart the server if it crashes. On my server, I launch it as screen ./run.sh.

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
respawn limit 2 60

chdir /home/ubuntu/sync

script
  exec /home/ubuntu/sync/run.sh
end script

emits CyTube-running 
EOF

Next, start the service using upstart:

sudo service cytube start

Maintenance

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.

Backups

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;
        server_name sub.example.com;

        ssl_prefer_server_ciphers on;
        ssl_certificate /etc/letsencrypt/live/sub.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/sub.example.com/privkey.pem;

        location ~ .* {
                proxy_pass http://127.0.0.1:8080;
                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
listen:
  - ip: ''
    port: 8080
    http: true
  - ip: ''
    port: 8443
    https: true
    io: true

http:
  root-domain: 'sub.example.com'

https:
  enabled: true
  default-port: 8443
  domain: 'https://sub.example.com'
  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 https://sub.domain.com:8443/socket.io/socket.io.js, 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/acme-v02.api.letsencrypt.org-directory/sub.domain.com/
-rw-r----- 1 caddy sitecerts 3141 Jan  8 23:54 sub.domain.com.crt
-rw------- 1 caddy caddy      149 Jan  8 23:54 sub.domain.com.json
-rw-r----- 1 caddy sitecerts  227 Jan  8 23:54 sub.domain.com.key

The location of Caddy's certificate files is /home/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/sub.domain.com/. 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
sub.domain.com {
        reverse_proxy localhost:1234
}

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

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

http:
  root-domain: 'sub.domain.com'

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

FBICHAN

Provide feedback

Saved searches

Use saved searches to filter your results more quickly