Here are my notes for installing speckle on a VM or VPS like server, using Debian 9.
Warning: These instructions are aimed at developers to test local deployments. This document should in no way be considered official installation instructions, and are explicitly not endorsed by Specke.
Warning: If you’re not proficient in linux administration and nodejs development to solve potential problems yourself, I highly recommend you use the official cloud based service.
Warning: This is a “this how I did it” document. Feel free to ask for help! Just be aware I have no affiliation with the speckle team and I will not take any responsibility for any consequences following these instructions may have for you.
This document assumes you have DNS setup for speckle.example.com
1. Basics.
-
This document assumes all commands are done from a non-root user. And that you have a decent initial server setup
-
The rest of this documentation assumes you’re signed in as
yournamewith sudo rights. -
I highly recommend you use a firewall. If you do, make sure to allow
httpandhttpsports through your firewall (mongodb and redis will may end up insecure and open to the world otherwise) -
I would also recommend something like fail2ban
-
Package requirements are:
sudo apt install curl apt-transport-https git build-essential
2. Install nodejs
Add nodejs apt repository, see documentation for alternatives
curl -sSL https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add -
VERSION=node_11.x
DISTRO="$(lsb_release -s -c)"
echo "deb https://deb.nodesource.com/$VERSION $DISTRO main" | sudo tee /etc/apt/sources.list.d/nodesource.list
echo "deb-src https://deb.nodesource.com/$VERSION $DISTRO main" | sudo tee -a /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install nodejs
3. Install speckle
More information on mongodb
More information on redis
sudo apt install mongodb redis-server
# Add speckle user
sudo adduser speckle
# Disable login for this user
passwd -l speckle
cd /home/speckle
sudo -u speckle git clone https://github.com/speckleworks/SpeckleServer.git
cd SpeckleServer
sudo -u speckle npm install
cd plugins
sudo -u speckle git clone https://github.com/speckleworks/SpeckleAdmin.git
4. Update configuration
cd /home/speckle/SpeckleServer
sudo cp .env-base .env
nano .env
# Change listen ip to 127.0.0.1
# Change url to https://speckle.example.com
# Test the speckle server to see if it will start
sudo -u speckle node server.js
You can close/kill the node server again, because we will use pm2 in the next steps.
TODO: Add documentation to harden the server permissions. @dimitrie do you know if are there any other folders than the log folder that need writing to?
5. Install pm2 process manager
Note: I’ve got no experience with pm2 at all, but it seems to work so far.
This will start the node server again if it crashes, and makes sure it will start on boot.
cd /home/speckle
sudo npm install -g pm2
sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u speckle --hp /home/
sudo -u speckle pm2 start server.js
6. Install nginx as a reverse proxy
sudo apt install ssl-cert nginx
nano /etc/nginx/sites-available/speckle
Add this config to the file
server {
listen 80;
server_name speckle.example.com;
location /.well-known {
alias /home/speckle/.well-known;
}
location / {
# redirect to https
return 301 https://$host$request_uri;
}
}
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# theoretically this can be a range of severs to facilitate
# horizontal scaling.
upstream speckleserver {
server 127.0.0.1:3000;
}
server {
# And: as far as I know websockets are not supported by http2 yet.
listen 443 ssl;
server_name speckle.example.com;
#dummy certificates, remove after letsencrypt certificate is generated.
ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
#ssl_certificate /etc/letsencrypt/live/speckle.example.com/fullchain.pem;
#ssl_certificate_key /etc/letsencrypt/live/speckle.example.com/privkey.pem;
ssl_stapling on;
ssl_stapling_verify on;
# log access + errors
access_log /var/log/nginx/speckle.log combined;
# maintain the .well-known directory alias for renewals
location /.well-known {
alias /home/speckle/.well-known;
}
# This part might need a bit of tuning later on.
# I'm not 100% sure about the wide range of timeout options available.
location / {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
proxy_pass http://speckleserver;
proxy_read_timeout 86400;
}
}
Warning: Make sure you list at least an SSL Certificate on your vhost. On ubuntu you can create a self signed certificate
Enable the config file:
sudo ln -s /etc/nginx/sites-available/speckle /etc/nginx/sites-enabled/speckle
sudo systemctl restart nginx
Your speckle server should now be reachable through http and https on port 80 and port 443.
7. Install SSL certificate with letsencrypt
echo "deb http://http.debian.net/debian stretch-backports main contrib non-free\n" | sudo tee /etc/apt/sources.list.d/stretch-backports.list
sudo apt-get update
sudo apt-get install certbot -t stretch-backports
sudo certbot certonly --webroot -w /home/speckle -d speckle.example.com
Replace the commented lines in the nginx config file (ssl_certificate, ssl_certificate_key). Remove the lines containing snakeoil certificates, and uncomment the other two lines with the location of the letsencrypt certificate.
nano /etc/nginx/sites-available/speckle
sudo systemcl restart nginx
Ubuntu comments
@markcichy suggested the following things for ubuntu 18:
- Download/install Ubuntu Server 18.05.2 LTS (although it may have a higher overhead - about 3GB installed - it does have many useful monitoring tools out of box: htop, ifconfig, ufw, etc.) Tutorial initial server setup
- Edit your /etc/ssh/sshd_config to change default port immediately (prior to UFW config)
- NodeJS and NPM install, I used the PPA repo and seemed to get better results as it install 10.x as opposed to the 8.x that is available in the APT repo.
