Contribute

Anyone can contribute to Spoolman! Here is some information if you want to contribute.

Server/Backend (Python)

The Python backend is built using Python 3.10 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 uv if you haven't already got it. See the uv installation instructions on their website.
4. Install Spoolman dependencies: uv sync
5. Basic setup done!

Poe the Poet is used to create commands for the python backend. It's entirely optional, but if you install it you can run e.g. poe run to start the python backend, or poe itest to run integration tests. If you don't have poe, you can look in pyproject.toml to see what those commands would do and then run them yourself.

Style

Ruff is used to ensure a consistent style, format and good code quality. You can install extensions in your editor to make them run automatically.

lefthook can be used to ensure all code (both backend Python and frontend Typescript) that you commit adhere to the standards. It integrates with git and prevents your commit from being made if it breaks the standards. It's optional but recommended since the CI pipeline will fail you otherwise in your pull request. See the installation instructions on lefthook's website. Run lefthook install once inside the Spoolman folder to activate the git integration for the repo. You can manually run all checks by doing lefthook run pre-commit.

Integration Testing

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 poe itest for all databases, or e.g. poe itest postgres for a single database.

Client (Node/React/Typescript)

The client is a React-based web client, built using the refine.dev framework, with Ant Design as the components.

To test out changes to the web client, the best way is to run it in development mode.

Prerequisites:

• NodeJS 20 or above installed, along with NPM. Running node --version should print a correct version.
• A running Spoolman server, with the following two environment variables added in the docker-compose.yml:

    environment:
      - FORWARDED_ALLOW_IPS=*
      - SPOOLMAN_DEBUG_MODE=TRUE

Instructions:

1. Open a terminal and CD to the client subdirectory
2. Run npm install. If it doesn't succeed, you probably have an incorrect node version. Spoolman is only tested on NodeJS 20.
3. Run echo "VITE_APIURL=http://192.168.0.123:7901/api/v1" > .env, where the ip:port is the address of the running Spoolman server. This should create a .env file in the client directory. If you don't already have one running on your network, you can start one up using the docker-compose.yml showed above.
4. Run npm run dev. The terminal will print a "Local: xxxx" URL, open that in your browser and the web client should show up. Your existing spools etc in your Spoolman database should be loaded in.
5. Any edits in .ts/.tsx files will be automatically reloaded in your browser. If you make any change to .json files you will need to F5 in your browser.