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.

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)

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.