Inventaire: a Docker image packaging:
- the Inventaire server
- the client
- the embedded database: LevelDB
CouchDB: the primary database used by the Inventaire server
Elasticsearch: a secondary database used by Inventaire for text and geographic search features
Nginx: a reverse proxy with TLS termination thank to Let's Encrypt certbot.

The service orchestration is implemented using Docker Compose.

🔧 This document is for people wanting to self-host the full Inventaire Suite. If you are looking for the individual Inventaire image, head over to hub.docker.com/r/inventaire/inventaire.

💡 This document presumes familiarity with basic Linux administration tasks and with Docker and Docker Compose.

Summary

Requirements
Install
Reverse proxy configuration
Usage
Tips
Troubleshooting
- Elasticsearch errors
- Quieting CouchDB notice

Quickstart

Requirements

Hardware

Network connection with a public IP address
4 GB RAM
10 GB free disk space

Software

Docker >= v22.0
Docker compose >= v2
git

Domain name

You need a DNS records that resolves to your machine's public IP address

Initial setup

Download this repository

git clone https://git.inventaire.io/docker-inventaire.git
cd docker-inventaire

Initial configuration

Rename dotenv file to .env, and customize the variables (mainly adding the domain name, and a couchdb password):

cp dotenv .env
vim .env

Clone inventaire core application server

git clone https://git.inventaire.io/inventaire.git

Build

docker-compose build

Download Node dependencies and install the client repository:

cd inventaire
npm install tsx && npm install
cd ..

Configure inventaire so that it can connect to CouchDB. For that, create a file config/local-production.cjs with the following command:

echo "module.exports = {
  db: {
    hostname: 'couchdb',
  },
  elasticsearch: {
    origin: 'http://elasticsearch:9200',
  }
}
" > ./inventaire/config/local-production.cjs

Reverse proxy configuration

Inventaire only provides configuration files for Nginx.

Run dependencies:

sudo mkdir -p /tmp/nginx/tmp /tmp/nginx/resize/img/users /tmp/nginx/resize/img/groups /tmp/nginx/resize/img/entities /tmp/nginx/resize/img/remote /tmp/nginx/resize/img/assets

Install nginx and certbot

Copy the nginx configuration template

PUBLIC_HOSTNAME=$(grep -oP 'PUBLIC_HOSTNAME=\K.*' .env) PROJECT_ROOT=$(grep -oP 'PROJECT_ROOT=\K.*' .env) envsubst < nginx/templates/default.conf.template > nginx/default
sudo mv nginx/default /etc/nginx/sites-available/default

Activate the configuration file

sudo ln -s /etc/nginx/sites-available/default.conf /etc/nginx/sites-enabled/default.conf

To generate the certificate for your domain as required to make https work, you can use Let's Encrypt:

sudo systemctl stop nginx
sudo certbot certonly --standalone --post-hook "systemctl restart nginx"
sudo systemctl restart nginx

When certbot is done, you may uncomment lines starting with # ssl_certificate and # ssl_certificate_key in /etc/nginx/sites-available/default.conf and restart nginx.

Certbot should have installed a cron to automatically renew your certificate. Since nginx template supports webroot renewal, we suggest you to update the renewal config file to use the webroot authenticator:

# Replace authenticator = standalone by authenticator = webroot
# Add webroot_path = /var/www/certbot
sudo vim /etc/letsencrypt/renewal/your-domain.com.conf

Usage

Start CouchDB, Elasticsearch, and the Inventaire server in production mode

docker-compose up

Tips

General tips on how to run Inventaire can be found in the server repository docs. Here after are some additional Docker-specific tips.

Fixtures

In case you would like to play with out-of-the-box data.

Run API tests to populate tests dbs

docker-compose -f docker-compose.yml exec inventaire npm run test-api

Replicate *-tests dbs documents into * dbs

`docker-compose exec inventaire npm run replicate-tests-db`

Path autocomplete

Create a symbolic link on your machine between the inventaire folder and docker working directory on your machine at /opt/, in order to autocomplete path to test file to execute

sudo ln ~/path/to/inventaire-docker/inventaire /opt -s

Alternatively, as root in inventaire container:

mkdir /supervisor/path/to/inventaire
ln -s /opt/ /supervisor/path/to/inventaire

Run inventaire server and client outside of Docker

It can sometimes be more convenient to keep CouchDB and Elasticsearch in Docker, but to run the Inventaire server and client outside. For this, you will need to have NodeJS >= v16 installed on your machine, which should make both node and npm executables accessible in your terminal

Then you can start CouchDB and Elasticsearch in the background

docker-compose up couchdb elasticsearch -d

Start the Inventaire server in development mode

cd inventaire
npm run watch

And in another terminal, start the client Webpack dev server

cd inventaire/client
npm run watch

Troubleshooting

Elasticsearch errors

max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]: fix by running the command sudo sysctl -w vm.max_map_count=262144 on your host machine

Quieting CouchDB notice

CouchDB may warn constantly that _users database does not exist, as documented, you can create de database with:

curl -X PUT http://127.0.0.1:5984/_users