🧰 Installation

Notivae is designed to be easy to self-host with Docker. The entire stack - frontend, backend and database - is orchestrated using docker-compose.

🔧 Prerequisites

Before you begin, make sure you have:

Docker installed
Install Docker
Docker Compose installed
Install Docker Compose
Your system must meet the minimum requirements

You will need a docker-compose.yml file to run Notivae. This file defines the services (frontend, backend, database), ports, and volumes.

You will also need a .env file. This file configures the behavior of the services.

Copy the following files to your local machine or server. We recommend placing them under /srv/notivae-stack. The docker-compose.yml should work out-of-the box but could be adjusted to your needs. The .env file must be customized to match your environment.

Your folder structure should look like this:

text

📁 /srv/notivae-stack
 ┣ 📄 docker-compose.yml
 ┗ 📄 .env

WARNING

These configuration files are currently in draft status and are not fully functional. Use them as a reference or base for manual setup until stable versions are released.

docker-compose.yml.env

yml

services:
  backend:
    image: ghcr.io/notive/backend
    ports:
      - "8765:8765"
    env_file: .env
    volumes:
      - nvdata:/data
    depends_on:
      - postgres
      - redis

  frontend:
    image: ghcr.io/notive/frontend
    ports:
      - "8766:8766"
    env_file: .env

  postgres:
    image: postgres
    env_file: .env
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis
    env_file: .env

volumes:
  nvdata:
  pgdata:

dotenv

# ----------------------------------------
# Backend Debugging & Logging
# ----------------------------------------

# Enables debug mode across the app.
# Should be False in production to avoid exposing sensitive details.
DEBUG=False

# Minimum severity level of log messages to be output.
# Options:
#   DEBUG    - Most verbose, shows everything (useful for local dev).
#   INFO     - General runtime information (default for production).
#   WARNING  - Things that might be problems in the future.
#   ERROR    - Runtime errors that should be investigated.
#   CRITICAL - Application or system-wide failures.
# Use DEBUG for local development, INFO or WARNING for production.
LOGGING_LEVEL=INFO

# Format used for application logs.
#   console - Human-readable format, ideal for terminal output.
#   json    - Structured logs, preferred for log ingestion (e.g., ELK, Loki).
LOGGING_FORMAT=console

# If enabled, logs will also be written to the database in addition to stdout.
# Useful for persistent audit logs or advanced querying.
LOG_TO_DB=True

# ----------------------------------------
# Backend Server Configuration
# ----------------------------------------

# The IP address the backend server will bind to.
# Common values:
#   0.0.0.0 - Bind to all network interfaces (use in Docker or remote envs).
#   127.0.0.1 - Bind to localhost only (useful for local testing).
APP_HOST=0.0.0.0

# The port the backend server will listen on.
# Must be an integer between 1 and 65534.
APP_PORT=8765

# ----------------------------------------
# Database Configuration
# ----------------------------------------

# The full database connection URL used by the backend service to connect
# to PostgreSQL. This should follow the format:
#   dialect+driver://username:password@host:port/database
#   e.g. postgresql+asyncpg://notivae:devpass@postgres/notivae
# If you are using Docker Compose, this should typically point to the
# internal Docker service name (e.g., `postgres`) instead of `localhost`.
DATABASE_URL=postgresql+asyncpg://notivae:devpass@localhost:5432/notivae

# The number of persistent database connections maintained per application worker.
# Increase this value for high-throughput systems with lots of concurrent queries.
DATABASE_POOL_SIZE=5

# The number of temporary connections that can exceed the pool size during peak usage.
# These "overflow" connections are not persistent and will be discarded after use.
DATABASE_POOL_MAX_OVERFLOW=10

# Maximum time (in seconds) to wait for a database connection before failing.
# Prevents application hangs under connection saturation or DB outage.
DATABASE_POOL_TIMEOUT=30

# Time (in seconds) after which idle database connections will be recycled.
# Helps prevent stale or broken connections in long-lived environments.
DATABASE_POOL_RECYCLE=1800

# ===================================================
# PostgreSQL Container Configuration (Docker Compose)
# ===================================================

# The username that will be created in the Postgres container.
# This must match the user part of DATABASE_URL.
POSTGRES_USER=notivae

# The password assigned to POSTGRES_USER.
# Used for authenticating from the backend or any external tool.
# This must match the password part of DATABASE_URL.
POSTGRES_PASSWORD=devpass

# The name of the default database that will be created in the container.
# This must match the database name in DATABASE_URL.
POSTGRES_DB=notivae

# ----------------------------------------
# GZip Compression Configuration
# ----------------------------------------

# Minimum size in bytes a response must reach before gzip compression is applied.
# This helps avoid wasting CPU cycles compressing small payloads that won't benefit.
GZIP_COMPRESSION_MINIMUM_SIZE=1000

# Compression level to use when gzip is enabled.
# 1 = Fastest, lowest compression ratio.
# 9 = Slowest, highest compression ratio.
# 6 is the recommended default for balanced performance.
GZIP_COMPRESSION_LEVEL=6

Once you have it in place:

bash

docker compose up -d

This will:

Start the backend API
Start the Database
Start the frontend
Initialize persistent volumes and expose the ports of the backend and frontend

✅ Verify

After a few seconds, open your browser to:

http://localhost:8766

You should see the Notivae welcome screen or a prompt to sign up

🔁 Updating

To update Notivae to the latest version:

shell

docker-compose pull
docker-compose up -d

This will fetch the latest version and restart the services.

🛑 Stopping the Stack

To stop the instance:

shell

docker-compose down

🧪 Development Setup

If you're contributing, see the Contributing guide for instructions on running each component in dev mode outside Docker.

🧰 Installation ​

🔧 Prerequisites ​

✅ Verify ​

🔁 Updating ​

🛑 Stopping the Stack ​