haul

README

Inventory management system for patchwork assets.

warning

This project is under heavy development, AND in a pre-release state.

Please do not use in production, as there is no guaranteed stability with the API or the database at this moment.

attributions

The wheelbarrow logo is owned by @k_coyote and used by the haulproject with permission.

It is licensed under CC BY-NC-SA 4.0. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/

API specification

haul provides its API server documentation in the form of a pave spec. Pre-generated specs are available in the wiki.

prerequisites

To build and deploy the server:

• docker

• docker-compose

To build the client:

• go

• git (optional, for automatic filling of haul version)

upgrade guide

if you are upgrading to version >=0.101.0, you will notice that your existing database (if it was deployed by docker-compose) is no longer useable, as the version of the postgres image was bumped from 14 to 16. The effect of this is that existing databases will refuse to boot on the new versions, because of PostgreSQL major version mismatch

Here is how you can import your existing database if you are affected by this change:

1. Revert back to v0.100.2, the latest version to not include the postgres 14 -> 16 bump
2. After successful deployment, gain access to the machine running the application. In the case of docker-compose, you can use the command $ docker-compose exec -it api sh to gain a shell inside the API server container.
3. Once inside, use the $ haul server export command to check your assets, attributes and tags total.
4. Use $ haul server export --json > haul_export.json command to export all your assets to the haul_export.json file
5. Copy the file somewhere that it won't be lost on container reboot. This can be the /etc/haul/ directory if using the default docker-compose.yaml
6. Exit out of the container shell, and upgrade haul to the latest version.
7. If using the default docker-compose.yaml, you will need to deal with the old postgres_data volume which won't be compatible anymore. Either rename or delete it.
8. Start the application with whatever method you normally use. With the default environment, use $ make deploy which uses docker-compose.
9. After verifying that everything is running smoothly (except for the empty database), obtain a new shell into the application. Again, in the case of the default environment with docker-compose, use $ docker-compose exec -it api sh.
10. Navigate to the directory where you stored the haul_export.json file, confirming that the content is what it is supposed to be.
11. Insert the data inside the empty database with $ haul server import haul_export.json, which supports both json and yaml formats. This will add all the entries from your old database, including the copying over of object ids, tags, etc. Note that it will rollback and exit if there is any overlap of ids of the same entity type (assets, attributes, and tags)

quickstart

haul itself is a binary executable, made with go, that can act both as a JSON API server or a CLI client.

The actual data is stored in a PostgreSQL database, which the reference implementation deploys alongside the server using docker-compose.

Nothing stops you from deploying it in a backed-up cluster, though!

Setup your database credentials

To get started quickly, all you need is to create a .env file in this project repository containing the following data:

Replace haul in production with something harder to guess

# .env
HAUL_POSTGRES_DATABASE=haul
HAUL_POSTGRES_PASSWORD=haul
HAUL_POSTGRES_USER=haul

This will accomplish two things:

1. If no database was previously created, it uses the information in the .env file to initialize a new database and user. This is done by mapping the values to their equivalent in the official PostgreSQL container image.

2. The database informations are passed to the API server using spf13/viper AutomaticEnv, overwriting the default config values.

Once that is done, you can deploy the server and database.

Deploy the server and database

Deploy both the API server and the PostgreSQL as docker containers locally using docker-compose

If you have git installed, you can include the git tag as a version number for haul version using:

$ docker-compose build --build-arg haul_version=`git describe`

You can then deploy the server and database using:

$ docker-compose up -d

(Optional) Install the CLI

Unless you intend to use a third-party API client or curl, you probably want to install the official go client;

There is currently no official automatic building of executables for haul.

The official way to get the client is to build it from source, which is relatively painless but requires go installed. See below for 2 options amongst many for installation.

Option 1: with git installed

To install the app to $HOME/go/bin and automatically fill the haul version command with the current git tag in the commit:

$ go install -ldflags="-X 'codeberg.org/haulproject/haul/build.version=`git describe`'"

Option 2: without git installed

Alternatively to last step, if you do not have git installed (or just don't care about version to be embedded in the executable):

$ go install

If codeberg.org/haulproject/haul/build.version is not filled, it defaults to printing haul version unknown which does not affect anything else in the app currently.

Check API server

To see API server health, you can:

• use the official haul cli you potentially just installed;

• make an API request yourself to check any API endpoint (defined in apihandler package);

• write your own client based on the client in apiclient, the API request inputs in apirequest and the API request outputs in apiresponse;

• ...

Assuming you chose to use the haul CLI, you should be able to check version using:

$ haul version

Which will return haul version unknown if the version was not provided as a build flag

To check API server health use:

$ haul health

Which as of v0.80.0 is the equivalent of:

GET /v1/health with key authentication

Make note that key authentication is on by default for all routes, default key is haul

You can explore the rest of the CLI with :

$ haul help

Documentation

Overview

Copyright © 2023 The Haul Authors

Inventory management system for patchwork assets.