Installation

Overview

Invenicum is designed to be self-hosted and can be deployed in several ways. This guide covers all deployment methods, from the simplest Docker Compose setup to standalone Docker containers.

Recommended Method: We recommend using Docker Compose for most users, as it handles both the application and database setup automatically.

Prerequisites

Before installing Invenicum, ensure you have:

Docker (version 20.10 or higher) and Docker Compose (version 2.0 or higher)
Google Gemini API Key - Get one free here
At least 2GB of RAM and 5GB of disk space
A supported platform: Linux, macOS, or Windows with WSL2

Installation Methods

Docker Compose (Recommended)
Docker Standalone
From Source (Development)

Docker Compose Setup

This is the easiest and recommended method for most users.

Create Project Directory

Create a new directory for your Invenicum installation:

mkdir invenicum
cd invenicum

Create Docker Compose File

Create a docker-compose.yml file with the following content:

docker-compose.yml

services:
  app:
    image: ghcr.io/lopiv2/invenicum:latest
    ports:
      - "3000:3000"
    environment:
      - DB_URL=postgres://user:pass@db:5432/invenicum
      - AI_PROVIDER=gemini
      - GEMINI_API_KEY=your_google_gemini_key_here
      - API_URL=http://localhost:3000
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    volumes:
      - ./data/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=invenicum
    restart: unless-stopped

Security: Change the default database credentials (user and pass) to strong, unique values before deploying to production.

Configure Environment Variables

Update the environment variables in your docker-compose.yml:

GEMINI_API_KEY: Your Google Gemini API key
DB_URL: PostgreSQL connection string (update credentials if changed)
API_URL: The URL where Invenicum will be accessible

Example for remote access:

- API_URL=http://192.168.1.100:3000

Start the Services

Launch Invenicum with:

docker-compose up -d

Check the logs to ensure everything started correctly:

docker-compose logs -f

Access the Application

Open your browser and navigate to:

http://localhost:3000

You’ll be prompted to create an admin account on first launch.

Updating

To update to the latest version:

docker-compose pull
docker-compose up -d

Stopping and Removing

To stop Invenicum:

docker-compose down

To remove all data (⚠️ this will delete your database):

docker-compose down -v
rm -rf ./data

Standalone Docker Setup

If you prefer to manage the database separately or use an existing PostgreSQL instance:

Set Up PostgreSQL

First, create a PostgreSQL database. You can use an existing server or run one in Docker:

docker run -d \
  --name invenicum-db \
  -e POSTGRES_USER=invenicum \
  -e POSTGRES_PASSWORD=secure_password_here \
  -e POSTGRES_DB=invenicum \
  -v invenicum-db-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:15-alpine

Run Invenicum Container

Launch the Invenicum application:

docker run -d \
  --name invenicum-app \
  -p 3000:3000 \
  -e DB_URL="postgres://invenicum:secure_password_here@localhost:5432/invenicum" \
  -e AI_PROVIDER=gemini \
  -e GEMINI_API_KEY="your_gemini_api_key" \
  -e API_URL="http://localhost:3000" \
  --restart unless-stopped \
  ghcr.io/lopiv2/invenicum:latest

If the database is running in another Docker container, use --link invenicum-db or put both containers on the same Docker network.

Verify Installation

Check the container logs:

docker logs -f invenicum-app

Access the application at http://localhost:3000

Building from Source

For developers or those who want to customize Invenicum:

Clone the Repository

git clone https://github.com/lopiv2/invenicum.git
cd invenicum

Install Dependencies

Make sure you have Flutter SDK installed (version 3.9.0 or higher):

flutter pub get

Configure Environment

Create or update the API URL configuration in lib/config/environment.dart:

static const String apiUrl = String.fromEnvironment(
  'API_URL',
  defaultValue: 'http://localhost:3000',
);

Run for Web

flutter run -d chrome --dart-define=API_URL=http://localhost:3000

Build for Production

For web deployment:

flutter build web --release --dart-define=API_URL=http://your-server:3000

The built files will be in the build/web directory.

Building from source requires a backend server. The Flutter app is the frontend only. Make sure you have the backend API running separately.

Environment Variables

Here’s a complete reference of all environment variables used by Invenicum:

Variable	Required	Default	Description
`DB_URL`	Yes	-	PostgreSQL connection string (format: `postgres://user:pass@host:port/dbname`)
`AI_PROVIDER`	Yes	`gemini`	AI provider (currently only `gemini` is supported)
`GEMINI_API_KEY`	Yes	-	Your Google Gemini API key for AI features
`API_URL`	Yes	`http://localhost:3000`	Base URL where the API is accessible
`PORT`	No	`3000`	Port the application listens on
`NODE_ENV`	No	`production`	Environment mode (`development` or `production`)

Frontend Environment Variables

When building the Flutter app, you can configure:

Variable	Default	Description
`API_URL`	`http://192.168.1.43:3000`	Backend API URL (set via `--dart-define`)

For production deployments, always override the default API_URL to point to your actual server.

Database Setup

PostgreSQL Requirements

Version: PostgreSQL 12 or higher (15 recommended)
Storage: At least 1GB free space (grows with your collection)
Encoding: UTF-8

Manual Database Setup

If you’re using an external PostgreSQL server:

CREATE DATABASE invenicum;
CREATE USER invenicum WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE invenicum TO invenicum;

Then construct your connection string:

postgres://invenicum:your_secure_password@your-db-host:5432/invenicum

Gemini API Configuration

Getting Your API Key

Visit Google AI Studio
Sign in with your Google account
Click “Create API Key”
Copy the key and add it to your environment variables

API Key Limits

The free tier includes:

15 requests per minute
1,500 requests per day
Suitable for personal use and small teams

For higher limits, check Google’s pricing page.

Keep Your API Key Secret: Never commit your API key to version control or share it publicly. Anyone with your key can use your Gemini quota.

Network Configuration

Accessing from Other Devices

To access Invenicum from other devices on your network:

Update the API_URL environment variable to use your server’s IP:
```
- API_URL=http://192.168.1.100:3000
```
Ensure port 3000 is accessible through your firewall:
```
# For Ubuntu/Debian
sudo ufw allow 3000/tcp
```

Reverse Proxy Setup

For production deployments with HTTPS, use a reverse proxy like Nginx or Traefik:

server {
    listen 80;
    server_name invenicum.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Troubleshooting

Database Connection Failed

If you see database connection errors:

Verify the DB_URL format is correct
Check that PostgreSQL is running: docker-compose ps
Ensure the database user has proper permissions
Check the logs: docker-compose logs db

AI Features Not Working

If AI features aren’t responding:

Verify your GEMINI_API_KEY is correct
Check you haven’t exceeded rate limits
Ensure your API key is active in Google AI Studio
Review application logs for specific error messages

Port Already in Use

If port 3000 is already occupied:

Change the port mapping in docker-compose.yml:

ports:
  - "8080:3000"  # Access via port 8080 instead

Update your API_URL accordingly:
```
- API_URL=http://localhost:8080
```

Next Steps

Now that Invenicum is installed:

Quick Start

Create your first collection and add items

Configuration

Customize Invenicum to fit your needs

Get Started

Core Features

Configuration

User Guide

Advanced

Overview

Prerequisites

Installation Methods

Docker Compose Setup

Updating

Stopping and Removing

Standalone Docker Setup

Building from Source

Environment Variables

Frontend Environment Variables

Database Setup

PostgreSQL Requirements

Manual Database Setup

Gemini API Configuration

Getting Your API Key

API Key Limits

Network Configuration

Accessing from Other Devices

Reverse Proxy Setup

Troubleshooting

Database Connection Failed

AI Features Not Working

Port Already in Use

Next Steps

Quick Start

Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

User Guide

Advanced

​Overview

​Prerequisites

​Installation Methods

​Docker Compose Setup

​Updating

​Stopping and Removing

​Standalone Docker Setup

​Building from Source

​Environment Variables

​Frontend Environment Variables

​Database Setup

​PostgreSQL Requirements

​Manual Database Setup

​Gemini API Configuration

​Getting Your API Key

​API Key Limits

​Network Configuration

​Accessing from Other Devices

​Reverse Proxy Setup

​Troubleshooting

​Database Connection Failed

​AI Features Not Working

​Port Already in Use

​Next Steps

Quick Start

Configuration

Build docs developers (and LLMs) love

Overview

Prerequisites

Installation Methods

Docker Compose Setup

Updating

Stopping and Removing

Standalone Docker Setup

Building from Source

Environment Variables

Frontend Environment Variables

Database Setup

PostgreSQL Requirements

Manual Database Setup

Gemini API Configuration

Getting Your API Key

API Key Limits

Network Configuration

Accessing from Other Devices

Reverse Proxy Setup

Troubleshooting

Database Connection Failed

AI Features Not Working

Port Already in Use

Next Steps