Skip to content

CyTube 3.0 Installation Guide

Jump to bottom Edit New page
Calvin Montgomery edited this page Nov 6, 2018 · 54 revisions

This guide will walk you through installing and configuring CyTube on a Linux server. If you have questions, feel free to stop by IRC (irc.esper.net#cytube). calzoneman is the developer behind CyTube, but other users in the channel may be able to help as well. Note: I work full time, so I may not be able to get to your question immediately. Please stick around for a while if you don't get a response.

Table of Contents

  1. Requirements
  2. Installation of prerequisites
  3. Installation of CyTube 3.0
  4. Configuration
  5. Running
  6. Maintenance

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

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. However, due to the software used, it will not run on shared webhosting; it requires a VPS or dedicated server. I recommend at least 256MB RAM for a small server. People have gotten by with less, but having sufficient RAM for MySQL to hold the database in memory will improve performance.

Note 2017/12/01: It has been a while since I actually tested on a machine this small; it's possible the newer versions of the software and its dependencies require more memory. All official CyTube servers have at least 1GB RAM, although they are handling a lot more traffic than a smaller deployment would. TODO: this should be validated in a VM and the wiki updated.

NOTE: while CyTube itself does not use much memory, npm will happily eat up gigabytes installing the dependencies. You may need to use alternative installers, or temporarily increase the memory for installation if using a virtual machine.

CyTube has a standalone webserver, so it is not necessary to use Apache or another webserver to serve content. You may use a 3rd party webserver in reverse proxy mode if you wish. cytu.be runs nginx, which proxies back good requests to CyTube (and takes care of blocking bad requests and rate limiting before requests even reach CyTube). Configuring a reverse proxy is outside the scope of this guide.

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)

Installation of prerequisites

Dependencies

Debian / Ubuntu

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

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

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, and some of them bring in very large dependency trees (for example, babel). For this reason, npm install may attempt to consume several gigabytes of RAM and fail when running out of memory, which leads to errors due to an incomplete installation. On systems with a small amount of RAM, you can try using an alternative installer like pnpm:

sudo npm install -g pnpm node-gyp
rm -rf node_modules
pnpm install

If this does not work, you can try using my janky little script that installs modules one at a time: https://gist.github.com/calzoneman/73929b0215cc5332367b9283fdf18aec

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:

  • The server dynamically generates links as http://http.domain:http.port/path. If you want to override this, you can set http.full-address to the desired root. For example, http://cytu.be runs on port 8080, but I want requests to go through nginx on port 80 rather than http://cytu.be:8080, so I have full-address: 'http://cytu.be' in the http block of my configuration.
  • 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. 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
# 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'

FBICHAN

Add a custom sidebar
Clone this wiki locally