Get StartedInstallation

Installation

Comprehensive installation guide for Invenicum with multiple deployment options.

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 20.10+

And Docker Compose v2.0 or higher

Google Gemini API Key

Get one free here

2GB RAM / 5GB Disk

Minimum system requirements

Supported Platform

Linux, macOS, or Windows with WSL2

Installation Methods

Docker Compose

Recommended

Docker Standalone

From Source

Dev only

Docker Compose Setup Recommended

Step 01

Create Project Directory

mkdir invenicum
cd invenicum
Step 02

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.
Step 03

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:

Step 04

Start the Services

Launch Invenicum with:

docker-compose up -d

Check the logs to ensure everything started correctly:

docker-compose logs -f
Step 05

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

docker-compose pull
docker-compose up -d

Stopping

docker-compose down
# Add -v to remove data

Standalone Docker Setup

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

Step 01

Set Up PostgreSQL

terminal
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
Step 02

Run Invenicum Container

terminal
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 on the same Docker network.

Step 03

Verify Installation

docker logs -f invenicum-app

Building from Source Dev only

For developers or those who want to customize Invenicum:

Step 01

Clone the Repository

cd invenicum
Step 02

Install Dependencies

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

flutter pub get
Step 03

Configure Environment

Update the API URL in lib/config/environment.dart:

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

Run for Web

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

Build for Production

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

Complete reference of all environment variables used by Invenicum:

VariableRequiredDefaultDescription
DB_URLYes—PostgreSQL connection string
AI_PROVIDERYesgeminiAI provider (only gemini supported)
GEMINI_API_KEYYes—Your Google Gemini API key
API_URLYeslocalhost:3000Base URL where the API is accessible
PORTNo3000Port the application listens on
NODE_ENVNoproductionEnvironment mode

Frontend Environment Variables

When building the Flutter app, you can configure:

VariableDefaultDescription
API_URLhttp://192.168.1.43:3000Backend 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 12 or higher (15 recommended)
  • At least 1GB free space
  • UTF-8 encoding

Manual Database Setup

If you’re using an external PostgreSQL server:

CREATE DATABASE invenicum;
CREATE USER invenicum WITH
ENCRYPTED PASSWORD ‘your_pass’;
GRANT ALL PRIVILEGES ON DATABASE
invenicum TO invenicum;

Gemini API Configuration

Getting Your API Key

1

Visit Google AI Studio

2

Sign in with your Google account

3

Click “Create API Key”

4

Copy the key and add it to your environment variables

Free Tier Limits

Requests per minute15 RPM
Requests per day1,500 RPD
Suitable forPersonal & 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:

1. Update API_URL to use your server’s IP:

- API_URL=http://192.168.1.100:3000

2. Allow port 3000 through your firewall (Ubuntu/Debian):

sudo ufw allow 3000/tcp

Reverse Proxy Setup (HTTPS)

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

nginx.conf
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
  • 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
  • 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

Change the port mapping in docker-compose.yml:

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

Update your API_URL accordingly:

Next Steps

Now that Invenicum is installed:

Quick Start

Create your first collection and add items with AI assistance.

Configuration

Customize Invenicum to fit your needs with environment variables and integrations.

Previous

Quickstart

Next

AI Assistant (Veni)