-
Notifications
You must be signed in to change notification settings - Fork 234
CyTube 3.0 Installation Guide
This guide will walk you through installing and configuring CyTube on a Linux server.
- Requirements
- Installation of prerequisites
- Installation of CyTube 3.0
- Configuration
- Running
- Maintenance
- Appendix A: Example config using nginx with SSL
- 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).
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).
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).
- 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.
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
- 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
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
.
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
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
# 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;
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,', '');
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 calleddomain
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.
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.
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
.
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
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
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
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'
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'