Installation¶
Making your printer Karmen-ready¶
The easiest way is to get yourself a fully plug’n’play Karmen Pill.
For hobbyists, the de-facto standard for making your 3D printer accessible over the network is Octoprint. Its installation can be greatly simplified by using a Raspbian-derived image with a pre-configured installation called OctoPi that is designed for Raspberry Pi microcomputers.
Note
There might be other viable solutions, but at the moment, Karmen Hub supports only Karmen Pill and Octoprint.
Karmen Hub supports password-protected Octoprint instances as well, it is possible to attach an API token to a printer on the printer settings screen (the option is only available when Octoprint is actually password-protected).
Also, make sure that the Octoprint instance is accessible over the network from a computer on which Karmen Hub is running.
Installing Karmen Hub¶
Karmen Hub should run on any OS supporting Docker running on amd64
or arm/v7
architecture.
We recommend to use a standalone computer for it, namely a Raspberry Pi 4 is a great fit.
Docker can be easily installed on Raspberry Pi by running a few commands adapted from this
official blogpost.
We recommend to use a clean Raspbian image as a base for installing Karmen Hub.
If you use a freshly installed Raspbian image, make sure that you run sudo apt update && sudo apt upgrade -y && sudo reboot before installing docker. That updates the system to the latest version and performs a restart.
sudo apt install software-properties-common -y
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
sudo usermod -aG docker pi
sudo apt install docker-compose -y
sudo reboot
docker info
The last command should spit out a bunch of information about your docker installation.
The next step is to get a production bundle for Karmen Hub. You can get these in the
Releases section on our GitHub.
Just download the latest stable release.zip
to your Raspberry Pi’s home directory and unzip it.
cd
wget -O karmen.zip https://github.com/fragaria/karmen/releases/latest/download/release.zip
unzip karmen.zip
cd karmen
The directory karmen
now contains at least the following files:
docker-compose.yml
- A blueprint for all necessary servicesrun-karmen.sh
- A startup script you can use to launch karmenstop-karmen.sh
- A script you can use to stop karmenupdate.sh
- An update script that can bring your installation up to dateVERSION
- A file with a version number useful for troubleshooting
The database schema is created automatically upon the first start and is kept up to date during updates. The datafiles are created on your filesystem, not inside the container, so no data will be lost during Karmen Hub’s downtime.
Karmen Hub requires a little bit of configuration that is done exclusively
with environment variables. The only required one is KARMEN_SECRET_KEY
which you should
set to something secret. It is used for session encryption and should be unique for each installation.
Another super important environment variable is KARMEN_CLOUD_MODE
. If it is set to 0
, Hub will
try to work with Pills, Octoprints and printers available directly over the network. If it is set to
1
, the application presumes that it is running somewhere on the internet and the devices are
connected over a specialized websocket proxy that comes
preconfigured with Karmen Pill. When you are setting KARMEN_CLOUD_MODE
to 1
, you also need to provide
KARMEN_SOCKET_API_URL
variable which points to the websocket proxy instance.
If you want to allow users registration, tou need to configure a mailing service as well. Consult the configuration section for more information.
Finally, you can start all of the services. During the first startup, the script will automatically download (from Docker Hub) and run all of the necessary containers. This might take a few minutes. For the first and all other starts, you can use the shorthand script like this:
KARMEN_CLOUD_MODE=0 KARMEN_SECRET_KEY=something-secr3t ./run-karmen.sh
The browser-accessible frontend is then accessible on the standard HTTP port 80. Again, consult the configuration page for more configruation options including the used ports.
You can access the UI by accessing the public IP address of your machine, or by accessing the
<hostname>.local
address which is automatically provided by Raspbian. The default hostname
for standard Raspbian is raspberrypi
and can be changed from the command line by running the
raspi-config
program.
Note
Raspbian and OctoPi provide the
<hostname>.local
service via mDNS. This technology might not work on some clients without prior configuration.
You can stop everything by running
./stop-karmen.sh
You probably want to start Karmen every time your Raspberry Pi boots up. Arguably the easiest (but in no way perfect) method
is to add the following line at the end of your /etc/rc.local
file just before the exit 0
line:
KARMEN_CLOUD_MODE=0 KARMEN_SECRET_KEY=something-secr3t /home/pi/karmen/run-karmen.sh >> /home/pi/karmen/startup.log
This will also put all of the startup information into a logfile in case you need to debug a broken start of Karmen.
Be aware that this method starts all of the containers under a root
account, which might not be the best idea.
An alternative might be a systemd service which might be setup with a file like this:
[Unit]
Description=Karmen
DefaultDependencies=no
After=docker.service
[Service]
Environment="KARMEN_CLOUD_MODE=0"
Environment="KARMEN_SECRET_KEY=something-secr3t"
Environment="KARMEN_HOST=127.0.0.1"
Environment="KARMEN_PORT=3776"
User=pi
Group=users
ExecStart=/usr/bin/karmen
RemainAfterExit=yes
ExecStop=/usr/bin/karmen-stop
[Install]
WantedBy=multi-user.target
The /usr/bin/
scripts are just links to the aforementioned run-karmen.sh
and stop-karmen.sh
scripts.
You should also keep your installation up to date at all times.
After the installation is ready, you can proceed with your first run.