OctoFarm: Installation

How to setup OctoFarm

Due to OctoFarms code base it's very system agnostic. There are however some limitations to what systems MongoDB can be installed on, i.e. needs to be 64-bit.

It is NOT recommended to install OctoFarm on the same RaspberryPi you run OctoPrint from. Whilst OctoFarm isn't very resource intensive it does a lot of fast calculations and I wouldn't personally give it the possibility to interfere with an active print. If you we're to go this route, you would need MongoDB installed on another system that is always on... it's much easier to just provide OctoFarm with it's own system.

Currently there are no installation packages for specific systems either. Those are been worked on currently but will require some code re-factoring before available. For now I have tried to simplify the installation steps below as much as humanly possibly. You should just be able to copy and paste each command into your available system.

Support Browsers

Currently OctoFarms client is compiled with ES5 support in mind so it should work fine on pretty much all browsers. It does also have a responsive layout so it will work on mobiles but this is not the core focus of the applications web interface so experiences may vary.

Prerequisites

MongoDB - v3.6+
NodeJS - v12.18.4 (Recommended to use the LTS version)
NPM - v6+
OctoPrint - v1.3.9+

Installation Steps

Instructions for specific systems are listed below. Any issues please log a bug on github and choose Documentation Issue. New Issue!

Frequently Asked Questions

I've installed on Rasbian and can't access the web interface?

Rasbian doesn't currently support 64-bit so MongoDB doesn't work on that platform. You either need to use an alternative system to host MongoDB or install the Ubuntu-64bit image for RaspberryPi.

I've entered in the API key and OctoFarm still doesn't connect?

There are a few things to check here:

1. OctoPrint has CORS enabled and has been restarted

2. If your on OctoPrint version 1.4.1+ then the global API key no longer works for web socket authentication. You must generate a User/Application key within OctoPrint, this is done with the user dropdown on the main interface and detailed in the "OctoPrint Preparations" section.

3. Check the URL you entered into OctoFarm hasn't got any trailing slashes (/).

Docker Installation

Currently all docker images are built with linux/amd64 with debian stretch. OctoFarm has a few different installation tags for docker builds. There is also two versions of the docker image, One standalone package that is just OctoFarm and requires a separate MongoDB installation. The second is the Monolithic image and that comes pre-packaged with everything you need to run OctoFarm.

OctoFarm

latest: Pulls the latest master release

dev: Pulls the latest development release. (Bleeding edge features, only for testing)

{Version Tag}: Pulls a specific version

OctoFarm Monolithic (Big thanks to MearWolf!)

monolithic-latest: Pulls the latest master release

monolithic-dev: Pulls the latest development release. (Bleeding edge features, only for testing)

monolithic-{Version Tag}: Pulls a specific version

Mount Paths

None of these are required for normal operations of OctoFarm as the majority is stored in the database.

/app/logs Mount for persistent OctoFarm logs.

/scripts Required mount path if you want to use the OctoFarm Alerts feature.

/app/images Required mount path if you want to change the OctoFarm background. Also required to support the historical capture of STL Images generated by the Prusa/Ultimaker image plugins

Monolithic Paths

/data Required mount path to make database persistent.

Example Docker Run command

docker run -d --name octofarm -e "MONGO=mongodb://172.17.0.2/octofarm" -p4000:4000 octofarm/octofarm -e "TZ=America/Chicago" -v '{your persistent folder}/OctoFarm/logs/':'/app/logs/':'rw' -v '{your persistent folder}/OctoFarm/scripts/':'/scripts/':'rw'

Example Docker Compose

version: "3"
services:
  octofarm:
  container_name: octofarm
  image: octofarm/octofarm
  restart: always
  ports:
    - 4000:4000
  environment:
    - MONGO=mongodb://mongo/octofarm
  volumes:
    - {your persistent folder}/OctoFarm/logs:/app/logs
   - {your persistent folder}/OctoFarm/scripts:/scripts

OctoPrint Preparations

There are a few steps you need to take to allow OctoFarm to connect to OctoPrint correctly.

1. Make sure CORS is switched on and OctoPrint has been restarted...

2. Grab your OctoPrint instances API Key.
This can be generated in the User Settings dialog.

Note: since OctoPrint version 1.4.1 it is recommended to connect using the Application Key / User Key detailed below. Versions before that are fine using the Global API Key generated by OctoPrint.

Note: You will only need to complete 1 of the below steps.

2.1 You can generate a API Key from your current user.

Please note, this user currently requires Admin permission rights. If in doubt, it's usually the first user you have created.

2.2 You can generate a API Key for a specific application.

Please note, this user currently requires Admin permission rights. If in doubt, it's usually the first user you have created.

Linux (Ubuntu) Installation

Follow the steps below to get setup on a Linux Debian variant.

1. Install MongoDB

1.1 Add MongoDB repository key

wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -

1.2 Add MongoDB repository. (Choose correct ubuntu version)

Ubuntu 20.04:echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
Ubuntu 18.08:echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
Ubuntu 16.04:echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

1.3 Install MongoDB

sudo apt-get update && sudo apt-get install -y mongodb-org

1.4 Make sure MongoDB is running and start if not

sudo systemctl status mongod
sudo systemctl enable mongod
sudo systemctl start mongod

2. Install NodeJS LTS version 12 and dependencies

curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt -y install nodejs gcc g++ make

3. Check your nodejs version and make sure the correct one is installed

node --version

Output: v12.18.3

4. Install git

sudo apt install git

5. Download the latest master version of OctoFarm

git clone https://github.com/NotExpectedYet/OctoFarm.git

6. cd into the newly created OctoFarm folder

cd ~/OctoFarm

7. Edit the file '/config/db.js' with your favorite editor and update the mongodb url with your systems IP. (You can skip this step if your using a MongoDB database on the same host)

mongodb://localhost:27017/octofarm

8. Install pm2 globally (may require sudo)

npm install pm2 -g

9. Install OctoFarms dependencies and start the service. This could take a few moments.

npm start

10. Profit!

Congratulations you should now be able to open the OctoFarm interface on port 4000 of your systems IP address

http://{insert system IP}:4000

Starting OctoFarm as a service (straight after "npm start" with OctoFarm running)

1. Generate your system startup script. Some systems may not require the output command pasting back into your terminal, you can just skip to part 4.

pm2 startup

Example Output: sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u pi --hp /home/pi

2. Copy and paste the output of this command into your terminal and run it. Do not copy the example above, this is specific to your system!

3. Save the configuration

pm2 save

Linux (Debian) Installation

Follow the steps below to get setup on a Linux Debian variant.

1. Install MongoDB

1.1 Add MongoDB repository key

wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -

1.2 Add MongoDB repository. (Choose correct debian version)

Debian 10:echo "deb http://repo.mongodb.org/apt/debian buster/mongodb-org/4.4 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
Debian 9: echo "deb http://repo.mongodb.org/apt/debian stretch/mongodb-org/4.4 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

1.3 Install MongoDB

sudo apt-get update && sudo apt-get install -y mongodb-org

1.4 Make sure MongoDB is running and start if not

sudo systemctl status mongod
sudo systemctl enable mongod
sudo systemctl start mongod

2. Install NodeJS LTS version 12 and dependencies

curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt -y install nodejs gcc g++ make

3. Check your nodejs version and make sure the correct one is installed

node --version

Output: v12.18.3

4. Install git

sudo apt install git

5. Download the latest master version of OctoFarm

git clone https://github.com/NotExpectedYet/OctoFarm.git

6. cd into the newly created OctoFarm folder

cd ~/OctoFarm

7. Edit the file '/config/db.js' with your favorite editor and update the mongodb url with your systems IP. (You can skip this step if your using a MongoDB database on the same host)

mongodb://localhost:27017/octofarm

8. Install pm2 globally (may require sudo)

npm install pm2 -g

9. Install OctoFarms dependencies and start the service. This could take a few moments.

npm start

10. Profit!

Congratulations you should now be able to open the OctoFarm interface on port 4000 of your systems IP address

http://{insert system IP}:4000

Starting OctoFarm as a service (straight after "npm start" with OctoFarm running)

1. Generate your system startup script. Some systems may not require the output command pasting back into your terminal, you can just skip to part 4.

pm2 startup

Example Output: sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u pi --hp /home/pi

2. Copy and paste the output of this command into your terminal and run it. Do not copy the example above, this is specific to your system!

3. Save the configuration

pm2 save

Our History

MDB founded to help startups, and it still shapes the way we work today.

  1. Launched our website

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

  2. Got the first 100 users

    ...

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

  3. Raised $1.4 million in seed funding

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

  4. Team size increased to 20

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

Our History

MDB founded to help startups, and it still shapes the way we work today.

  1. Launched our website

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

  2. Got the first 100 users

    ...

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

  3. Raised $1.4 million in seed funding

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

  4. Team size increased to 20

    Lorem ipsum dolor sit amet consectetur adipisicing elit. Assumenda ullam adipisci reiciendis porro natus laudantium similique. Explicabo amet ipsum fugiat aliquam alias.

Raspberry Pi (with Ubuntu 64-bit)

Follow the steps below to get setup on a Raspberry Pi 3/4

1. Download the latest ubuntu 64 bit image from ubuntu.com

Raspberry Pi Ubuntu 64-bit
Make sure it's Ubuntu Server 20.04.1 LTS

2. Flash the image onto your microSD card. Thankfully there are some online guides from ubuntu you can follow.

Linux Machine

Windows Machine

Macs

3. Boot the ubuntu server after inserting the SD card.

4. If you haven't got a keyboard/mouse attached then you'll have to access you Pi's command line via the SSH protocol to run the steps in the next section.

5. Continue on with the Linux (Ubuntu) setup.