Speckle Server Debian 9 installation notes for development machines

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 yourname with sudo rights.

  • I highly recommend you use a firewall. If you do, make sure to allow http and https ports 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 -
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
# 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 {
    # 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.
1 Like

Thought I might as well ask here. There are quite a few things I have not managed to get working by going along with this without a number of installs. Imagine starting the most basic 5$ droplet from Digital Ocean using a Debian 9.7 install.

First you need to install these packages as they do not exist:

sudo apt install curl
sudo apt-get install apt-transport-https
sudo apt install git
sudo apt install build-essential

If you follow this step by step, you will notice that at step 4 there is no file to copy. So basically you have to cd back into SpeckleServer and do it there. And for some reason, the letsencrypt certificate does not always work.

I’ll add more as I discover other issues.

Thanks, I’ve added them.

Thanks, the cd SpeckleServer should have been a few lines before.

I’ll need a bit more information (what does not work? which errors? Is there a way to reproduce?) to help on that.

Well, I guess the best thing we could do is tackle it together and then we can add comments here. Thing is - from the windows powershell I created the certificates, but they are not trusted when you go on the website.

So basically a few searches in - No Support on Mozilla - Help - Let's Encrypt Community Support
And a redirect to this: [Solved] Why isn't my certificate trusted? - #2 by germeier - Server - Let's Encrypt Community Support

Could be we are missing the chain.pem from the speckle file we created and we need to add that in.

I’m wondering if there is a way to have your website trusted by web-browsers from the beginning not to have to add the website as an exception.

I think more context will still be needed - are you deploying this on a standard vm with a public IP? Are you using nginx as a proxy?

What confuses me is that you’re generating these on windows (powershell?) and not debian/ubuntu/etc. I’ve never really used a windows server setup, but i for sure imagine the cert generation route is different.

As a side note, i’ve found that recent version of certbot, on ubuntu at least, manage things really well - there’s even no need to fiddle with your nginx conf files.

So, using digital ocean - I’ve encountered an amusing issue. Even if you restart the nginx server - it still has an issue with the certificates and it does not trigger them. Firefox was acting as if there was no certificate so I had to add my website as an exception.

Sorry for the powershell confusion issue. I am clearly using debian - and putty to connect to the Digital Ocean droplet, so I made a confusion (though I am using windows).

The certificates work now, but only after power cycling the droplet itself.

And yes. Certbot is a lot more friendly for creating certificates. I can testify to using it and it work. If you want we can add it as an alternative.

After having a look over the console, I’d say this guide is solid for now, and should be good for at least a few more months, seeing as debian 9 end of life is in 2020.

Ok. So certbot works as well, confirm after a personal test - https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-debian-9 - this is where I got the info from. I use digital ocean so it was pretty straight forward for me.

Quick question - do we even need this step anymore? sudo -u speckle git clone https://github.com/speckleworks/SpeckleViewer.git - you say its deprecated and the Viewer now is in the Admin, so we could probably remove this step - to avoid any confusion or make a comment //if you want old viewer, do this?

No, good idea. I’ve removed the step.

Does this work with mac os?

1 Like

No. It only works on debian 9.

hello @chloesun (welcome to the forum! & excuse the late reply), as @avanwaart says, this guide is really just for debian. Nevertheless, the speckle server is actually developed on osx. to get it running there, you’ll need to:

Then, probably with some minor tweaks to the .env file, you’ll be good to go. Mind you, I didn’t follow the guides above, so can’t really vouch for their effectiveness. Hope this helps!

PS: You can always use https://hestia.speckle.works/api if you just want to play around.

1 Like

I’m going to add a comment RE Ubuntu v Debian for those that may be wondering out there. @avanwaart’s original play for Debian is correct–use Ubuntu for initial stack convenience only! The resource price is high. If optimization and resource utilization are critical factors for you (i.e. trying to build your own containers, working with limited resources, etc.), stick with Debian.
I was able to commit a fresh workable install of Debian 10 inside a VM to the tune of 8xx MB in size, with a consistent RAM utilization of only 150MB!!! Sure, once you install Redis and Mongo – among other tools/utilities you will cross the 3GB HDD and 325MB RAM barriers, but these still pale in comparison. My Ubuntu VM’s post config all routinely run at about 7-8GB HDD and 3GB RAM.
I just wanted to share this info with the group.
Of course, if you’re looking to build containers you’re probably already considering building upon the Arch Linux image–with only a base 85MB kernel install it is the best option in that regard (you could integrate networking resources and utilities and end up with a 350MB~ image and still be well under the above. :grinning: :100: :tada:
Hopefully these comments are useful to someone.