Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Donkie
Donkie committed Jun 8, 2024
1 parent 4b155a9 commit 111eab1
Showing 1 changed file with 68 additions and 68 deletions.
136 changes: 68 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,52 +4,82 @@
<img alt="Icon of a filament spool" src="https://github.com/Donkie/Spoolman/assets/2332094/3c120b3a-1422-42f6-a16b-8d5a07c33000">
</picture>

<br/><br/>
<br/>

_Keep track of your inventory of 3D-printer filament spools._

Spoolman is a web service that helps you keep track of your filament spools and how they are being used.
Spoolman is a self-hosted web service designed to help you efficiently manage your 3D printer filament spools and monitor their usage. It acts as a centralized database that seamlessly integrates with popular 3D printing software like [OctoPrint](https://octoprint.org/) and [Klipper](https://www.klipper3d.org/)/[Moonraker](https://moonraker.readthedocs.io/en/latest/). When connected, it automatically updates spool weights as printing progresses, giving you real-time insights into filament usage.

### Features
* **Filament Management**: Keep comprehensive records of filament types, manufacturers, and individual spools.
* **API Integration**: The [REST API](https://donkie.github.io/Spoolman/) allows easy integration with other software, facilitating automated workflows and data exchange.
* **Real-Time Updates**: Stay informed with live spool updates through Websockets, providing immediate feedback during printing operations.
* **Web-Based Client**: Spoolman includes a built-in web client that lets you manage data effortlessly:
* View, create, edit, and delete filament data.
* Add custom fields to tailor information to your specific needs.
* Print labels with QR codes for easy spool identification and tracking.
* Contribute to its translation into 18 languages via [Weblate](https://hosted.weblate.org/projects/spoolman/).
* **Database Support**: SQLite, PostgreSQL, MySQL, and CockroachDB.
* **Multi-Printer Management**: Handles spool updates from several printers simultaneously.
* **Advanced Monitoring**: Integrate with [Prometheus](https://prometheus.io/) for detailed historical analysis of filament usage, helping you track and optimize your printing processes.

**Integrations:**
* [Moonraker](https://moonraker.readthedocs.io/en/latest/configuration/#spoolman) and most front-ends (Fluidd, KlipperScreen, Mainsail, ...)
* [OctoPrint](https://github.com/mdziekon/octoprint-spoolman)
* [OctoEverywhere](https://octoeverywhere.com/spoolman?source=github_spoolman)
* [Homeassistant](https://github.com/Disane87/spoolman-homeassistant)

**Web client preview:**
![image](https://github.com/Donkie/Spoolman/assets/2332094/33928d5e-440f-4445-aca9-456c4370ad0d)

It acts as a database, where other printer software such as Octoprint and Moonraker can interact with to have a centralized place for spool information.
For example, if used together with Moonraker, your spool weight will automatically be reduced as your print is progressing.
## Installation
Spoolman can be installed in two ways, either using **Docker** or **standalone** on your machine.
* The Docker method can be used on any OS which supports Docker.
* The standalone method requires a Debian (e.g. Ubuntu, Raspberry Pi OS) or Arch-based Linux distribution.
* If you know what you're doing you can also install it standalone for any OS such as Windows, but there are no provided scripts for automated installation, follow the "Install from Source" instructions below.

It exposes a HTTP API which services can interact with. See the [OpenAPI description](https://donkie.github.io/Spoolman/) for more information.
Docker is the recommended installation method since it is more reliable and portable.

## Client
Spoolman includes a web-client that lets you directly manipulate all the data. It also has a few additional nice features such as label printing.
Spoolman comes with a built-in SQLite database that is used by default and will suit most users needs. The data is stored in a single .db file in the server's user directory. You can optionally instead use a PostgreSQL, MySQL or CockroachDB database.

![image](https://github.com/Donkie/Spoolman/assets/2332094/33928d5e-440f-4445-aca9-456c4370ad0d)
### Docker Install
#### First install
Docker is a platform for developing, shipping, and running applications in "containers". Containers are lightweight, portable, and self-contained environments that can run on any machine with Docker installed. The Spoolman docker image contains everything it needs to run, so you don't need to worry about for example what Python version you have installed on your local machine.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://hosted.weblate.org/widget/spoolman/287x66-black.png">
<source media="(prefers-color-scheme: light)" srcset="https://hosted.weblate.org/widget/spoolman/287x66-white.png">
<img alt="Icon of a filament spool" src="https://hosted.weblate.org/widget/spoolman/287x66-white.png">
</picture>

_The web client is translated by the community using [Weblate](https://hosted.weblate.org/projects/spoolman/)._
To install Docker on your machine, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/engine/install/). Docker also includes the docker-compose tool which lets you configure the container deployment in a simple yaml file, without having to remember all the command line options. Note: older versions of docker-compose require you to have a dash (`-`) in the following commands, like `docker-compose` instead of `docker compose`.

## Integration status
Spoolman doesn't depend on any specific printer software, but to make the most out of it, you should use it together with a frontend that supports it.
It is currently only supported in the Klipper ecosystem, with official support for the major frontends. Support for other ecosystems like Octoprint is ongoing.
Here is a sample docker-compose config to get you started. Create a folder called `spoolman` in your home directory, CD in to it, copy-paste the below sample into a file called `docker-compose.yml` in the new directory and run `docker compose up -d` to start it. If you want to use the SQLite database as in this sample, you must first create a folder called `data` in the same directory as the `docker-compose.yml`, then you should run `chown 1000:1000 data` on it in order to give it the correct permissions for the user inside the docker container.
```yaml
version: '3.8'
services:
spoolman:
image: ghcr.io/donkie/spoolman:latest
restart: unless-stopped
volumes:
# Mount the host machine's ./data directory into the container's /home/app/.local/share/spoolman directory
- type: bind
source: ./data # This is where the data will be stored locally. Could also be set to for example `source: /home/pi/printer_data/spoolman`.
target: /home/app/.local/share/spoolman # Do NOT modify this line
ports:
# Map the host machine's port 7912 to the container's port 8000
- "7912:8000"
environment:
- TZ=Europe/Stockholm # Optional, defaults to UTC
```
Once you have it up and running, you can access the web UI by browsing to `http://server.ip:7912`. *Make sure that the data folder you created now contains a `spoolman.db` file*. If you cannot find this file in your machine, then **your data will be lost** every time you update Spoolman.

* ✔️ Moonraker - See the [Moonraker Documentation](https://moonraker.readthedocs.io/en/latest/configuration/#spoolman)
* ✔️ Fluidd
* ✔️ KlipperScreen
* ✔️ Mainsail
* ✔️ Octoprint: [OctoPrint-Spoolman](https://github.com/mdziekon/octoprint-spoolman)
* ✔️ Home Assistant integration: [spoolman-homeassistant](https://github.com/Disane87/spoolman-homeassistant)
* ✔️ Free & Secure Remote Access: [OctoEverywhere for Spoolman](https://octoeverywhere.com/spoolman?source=github_spoolman)
Type `docker compose logs` in the terminal to see the server logs.

## Installation
Spoolman can interact with any of the following databases: SQLite, PostgreSQL, MySQL, MariaDB, CockroachDB.
By default, SQLite is used which is a simple no-install database solution that saves to a single .db file located in the server's user directory.
If you want to modify things like database connection, add environment variables to the `environment:` section of the `docker-compose.yml` like shown in the sample above and then restart the service: `docker compose restart`. See the `.env.example` file for a list of all environment variables you can use.

Spoolman can be installed in two ways, either standalone on your machine or using Docker. If you already have Docker installed, it's recommended to use that.
#### Updating
If a new version of Spoolman has been released, you can update to it by first browsing to the directory where you have the `docker-compose.yml` file and then running `docker compose pull && docker compose up -d`.

### Standalone
This installation guide assumes you are using a Debian-based Linux distribution such as Ubuntu or Raspberry Pi OS. If you are using another distribution, please look inside the bash scripts to see what commands are being run and adapt them to your distribution.
### Standalone Install
#### First install
This installation method assumes you are using a Debian-based Linux distribution such as Ubuntu or Raspberry Pi OS. If you are using Arch, or any other distribution, please modify as appropriate.

Copy-paste the entire below command and run it on your machine to install Spoolman.
Make sure your current directory is in your logged in user's home directory. Copy-paste the entire below command and run it on your machine to install the latest release of Spoolman.
```bash
sudo apt-get update && \
sudo apt-get install -y curl jq && \
Expand All @@ -60,6 +90,8 @@ cd ./Spoolman && \
bash ./scripts/install.sh
```

If you want to modify things like database connection, edit the `.env` file in the `Spoolman` folder and restart the service.

#### Updating
Updating Spoolman is quite simple. If you use the default database type, SQLite, it is stored outside of the installation folder (in `~/.local/share/spoolman`), so you will not lose any data by moving to a new installation folder.

Expand All @@ -82,37 +114,6 @@ bash ./scripts/install.sh && \
rm -rf ../Spoolman_old
```

### Using Docker
You can also run Spoolman using Docker. Docker is a platform for developing, shipping, and running applications in containers. Containers are lightweight, portable, and self-contained environments that can run on any machine with Docker installed.

To install Docker on your machine, follow the instructions for your operating system on the [Docker website](https://docs.docker.com/engine/install/). Docker also includes the docker-compose tool which lets you configure the container deployment in a simple yaml file, without having to remember all the command line options. Note: older versions of docker-compose require you to have a dash (`-`) in the following commands, like `docker-compose` instead of `docker compose`.

Here is a sample docker-compose config to get you started. Copy-paste it into a file called `docker-compose.yml` and run `docker compose up -d` to start it. If you want to use the SQLite database as in this sample, you must first create a folder called `data` in the same directory as the `docker-compose.yml`, then you should run `chown 1000:1000 data` on it in order to give it the correct permissions for the user inside the docker container.
```yaml
version: '3.8'
services:
spoolman:
image: ghcr.io/donkie/spoolman:latest
restart: unless-stopped
volumes:
# Mount the host machine's ./data directory into the container's /home/app/.local/share/spoolman directory
- type: bind
source: ./data # This is where the data will be stored locally. Could also be set to for example `source: /home/pi/printer_data/spoolman`.
target: /home/app/.local/share/spoolman # Do NOT change this line
ports:
# Map the host machine's port 7912 to the container's port 8000
- "7912:8000"
environment:
- TZ=Europe/Stockholm # Optional, defaults to UTC
```
Once you have it up and running, you can access the web UI by browsing to `http://your.ip:7912`. Make sure that the data folder you created now contains a `spoolman.db` file. If you cannot find this file in your machine, then **your data will be lost** every time you update Spoolman.

#### Updating
If a new version of Spoolman has been released, you can update to it by first browsing to the directory where you have the `docker-compose.yml` file and then running `docker compose pull && docker compose up -d`.

### Environment variables
See the `.env.example` file for a list of all environment variables you can use.

## Frequently Asked Questions (FAQs)
### QR Code Does not work on HTTP / The page is not served over HTTPS
This is a limitation of the browsers. Browsers require a secure connection to the server to enable HTTPS. This is not a limitation of Spoolman. For more information read this [blog](https://blog.mozilla.org/webrtc/camera-microphone-require-https-in-firefox-68/) from Mozilla.
Expand All @@ -122,13 +123,13 @@ This is a limitation of the browsers. Browsers require a secure connection to th
Another option is to put Spoolman behind a reverse proxy like Caddy or Nginx to enable HTTPS. See for example [this guide](https://caddyserver.com/docs/quick-starts/reverse-proxy) for Caddy.

### Can Spoolman be translated into my language?
Yes, head over to [Weblate](https://hosted.weblate.org/projects/spoolman/) to start the Translation
Yes, head over to [Weblate](https://hosted.weblate.org/projects/spoolman/) to start the translation!

## Install from source
**Advanced users only.**

If you want to run the absolute latest version of Spoolman, you can either use the `edge` tagged Docker image, or follow
these steps to install from source. Keep in mind that this may contain bugs and is not recommended for production use.
these steps to install from source. Keep in mind that this is straight from the master branch which may contain unfinished and untested features. You may also not be able to go back to a previous version since the database schema may change.

1. Make sure you have at least NodeJS 20 or higher installed, and Python 3.9 or higher installed.
1. Clone this repo or download the zip source.
Expand All @@ -143,13 +144,12 @@ these steps to install from source. Keep in mind that this may contain bugs and

## Development
### Server/Backend (Python)
The Python backend runs on Python 3.9. It's built on FastAPI for the REST API, and SQLAlchemy to handle the databases.
The Python backend is built using Python 3.9 standards. It's built on FastAPI for the REST API, and SQLAlchemy to handle the databases.

To setup yourself for Python development, do the following:
1. Clone this repo
2. CD into the repo
3. Install PDM: `pip install --user pdm`
> At pre-commit hook used pdm==2.7.4
4. Install Spoolman dependencies: `pdm sync`

And you should be all setup. Read the Style and Integration Testing sections below as well.
Expand All @@ -164,7 +164,7 @@ pre-commit install
```

#### Integration Testing
The entire REST API is integration tested using an isolated docker container, with all 4 database types that we support (Postgres, MySQL, SQLite and CockroachDB). These integration tests live in `tests_integration/`. They are designed to "use" the REST API in the same way that a client would, and ensures that everything remains consistent between updates. The databases are created as part of the integration testing, so no external database is needed to run them.
The entire backend is integration tested using an isolated docker container, with all 4 database types that we support (Postgres, MySQL, SQLite and CockroachDB). These integration tests live in `tests_integration/`. They are designed to "use" the REST API in the same way that a client would, and ensures that everything remains consistent between updates. The databases are created as part of the integration testing, so no external database is needed to run them.

If you have docker installed, you can run the integration tests using `pdm run itest` for all databases, or e.g. `pdm run itest postgres` for a single database.

Expand Down

0 comments on commit 111eab1

Please sign in to comment.