Installation Guide

This guide provides comprehensive instructions for installing Mantis in development and production environments.

System Requirements

Software Requirements

Component	Minimum Version	Recommended Version
Python	3.8	3.10+
PostgreSQL	12.x	14.x or higher
Node.js	20.19.0	22.12.0+
npm	9.x	10.x
Operating System	Ubuntu 20.04	Ubuntu 22.04 LTS

Hardware Requirements

Development Environment:

2 CPU cores
4 GB RAM
10 GB disk space

Production Environment:

4+ CPU cores
8+ GB RAM
50+ GB disk space (depending on media storage needs)

Installation Steps

1. System Preparation

Update System Packages

sudo apt update
sudo apt upgrade -y

Install Python and Dependencies

sudo apt install -y python3 python3-pip python3-venv python3-dev
sudo apt install -y build-essential libpq-dev

Install PostgreSQL

sudo apt install -y postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Install Node.js

Use nvm (Node Version Manager) for flexibility:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install Node.js
nvm install 22.12.0
nvm use 22.12.0
nvm alias default 22.12.0

# Verify installation
node --version
npm --version

2. Database Setup

Create PostgreSQL Database

Create a database and user for Mantis:

# Switch to postgres user
sudo -u postgres psql

In the PostgreSQL prompt:

-- Create database
CREATE DATABASE mantis;

-- Create user
CREATE USER mantis_user WITH PASSWORD 'secure_password_here';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE mantis TO mantis_user;

-- Grant schema permissions (PostgreSQL 15+)
\c mantis
GRANT ALL ON SCHEMA public TO mantis_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO mantis_user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO mantis_user;

-- Exit
\q

Use a strong, unique password in production. Never use the example password shown here.

Configure PostgreSQL Access

Edit PostgreSQL configuration to allow local connections:

# Edit pg_hba.conf
sudo nano /etc/postgresql/14/main/pg_hba.conf

Add or modify the following line:

# IPv4 local connections:
host    mantis          mantis_user     127.0.0.1/32            md5

Restart PostgreSQL:

sudo systemctl restart postgresql

Verify Database Connection

Test the connection:

psql -h localhost -U mantis_user -d mantis

Enter the password when prompted. If successful, you’ll see the PostgreSQL prompt.

3. Application Setup

Clone Repository

Clone the Mantis source code:

cd /opt  # or your preferred installation directory
git clone <repository-url> mantis
cd mantis

Create Python Virtual Environment

cd app/src
python3 -m venv venv
source venv/bin/activate

Always activate the virtual environment before running Django commands:

source /opt/mantis/app/src/venv/bin/activate

Install Python Dependencies

pip install --upgrade pip
pip install -r requirements.txt

If requirements.txt doesn’t exist, install core dependencies:

pip install django==4.2.14
pip install djangorestframework
pip install django-grappelli
pip install django-simple-history
pip install django-extensions
pip install django-cors-headers
pip install django-user-sessions
pip install django-crum
pip install psycopg2-binary
pip install pillow

Configure Database Connection

Create or edit the database configuration file:

nano common/secrets.py

Add your database configuration:

DATABASES = {
    'TEST': {
        "ENGINE": "django.db.backends.postgresql",
        'NAME': 'mantis_test',
        'USER': 'mantis_user',
        'PASSWORD': 'secure_password_here',
        'HOST': 'localhost',
        'PORT': '5432',
    },
    'PRODUCTION': {
        "ENGINE": "django.db.backends.postgresql",
        'NAME': 'mantis',
        'USER': 'mantis_user',
        'PASSWORD': 'secure_password_here',
        'HOST': 'localhost',
        'PORT': '5432',
    },
    'DEVELOPMENT': {
        "ENGINE": "django.db.backends.postgresql",
        'NAME': 'mantis_dev',
        'USER': 'mantis_user',
        'PASSWORD': 'secure_password_here',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

# Set the environment to use
DEFAULT_DB = {
    'default': DATABASES['PRODUCTION']  # or 'DEVELOPMENT' or 'TEST'
}

Security Best Practices:

Never commit secrets.py to version control
Add common/secrets.py to .gitignore
Use environment variables for sensitive data in production
Rotate passwords regularly

4. Django Migrations

Generate Initial Migrations

Create migrations for the core applications:

# For Unix/Linux
./manage.py makemigrations accounts
./manage.py makemigrations equipment projects

Or using Python directly:

python manage.py makemigrations accounts
python manage.py makemigrations equipment projects

The migrations must be created in this order due to model dependencies:

accounts (provides CustomUserModel)
equipment and projects (depend on accounts)

Apply Migrations

Run the migrations to create database schema:

./manage.py migrate

You should see output showing each migration being applied:

Operations to perform:
  Apply all migrations: accounts, admin, auth, contenttypes, equipment, projects, sessions, user_sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying accounts.0001_initial... OK
  ...

Seed Initial Data

Populate the database with required initial data:

./manage.py sowseed

This command seeds:

Default user groups and permissions
Initial equipment categories
System configuration data
Sample data (if applicable)

Populate History Tables

Initialize django-simple-history for existing records:

./manage.py populate_history --auto

This creates initial history records for audit trail functionality.

Create Superuser

Create an administrative account:

./manage.py createsuperuser

Enter:

Email: Your admin email address
Password: A strong password
First name and Last name (optional)

The user will be created with role='ADMINISTRATIVO' by default.

5. Frontend Setup

Navigate to Frontend Directory

cd /opt/mantis/app/client/mantis

Install Node Dependencies

npm install

This installs:

Vue.js 3.5.22
Vue Router 4.6.3
Pinia 3.0.3 (state management)
TailwindCSS 4.1.17
DaisyUI 5.4.7
Axios 1.13.2
Vite 7.1.11
Development tools

If you encounter peer dependency warnings, you can safely ignore them or run:

npm install --legacy-peer-deps

Build for Production

Compile and optimize the frontend:

npm run build

This command:

Builds the Vue.js application with Vite
Minifies JavaScript and CSS
Copies the largest JavaScript file to ../../src/static/js/app/app-projects.js
Copies CSS file to ../../src/static/css/app/app-projects.css

The build script automatically moves compiled assets to Django’s static directories, so they’re ready for collectstatic.

Development Mode (Optional)

For frontend development with hot reload:

npm run dev

The development server starts on http://localhost:5173 with:

Hot module replacement (HMR)
Source maps for debugging
Vue DevTools integration

6. Static Files Collection

Create Static Directories

cd /opt/mantis/app/src
mkdir -p static_django
mkdir -p media

Collect Static Files

Gather all static files from apps and copy to STATIC_ROOT:

./manage.py collectstatic --noinput

This collects:

Django admin static files
Grappelli admin theme assets
Vue.js compiled frontend assets
Application-specific static files

Set Permissions

sudo chown -R www-data:www-data /opt/mantis/app/src/static_django
sudo chown -R www-data:www-data /opt/mantis/app/src/media
sudo chmod -R 755 /opt/mantis/app/src/static_django
sudo chmod -R 755 /opt/mantis/app/src/media

Environment Configuration

Development Environment

For development, the default settings.py is configured appropriately:

DEBUG = True
ALLOWED_HOSTS = ['*']

Production Environment

Critical Security Settings for Production

Update Django Settings

Edit peisol/settings.py:

# Security settings
DEBUG = False
SECRET_KEY = 'your-unique-secret-key-here'  # Generate a new one!
ALLOWED_HOSTS = [
    'mantis.yourdomain.com',
    'www.mantis.yourdomain.com',
    'your-server-ip'
]

# CSRF settings
CSRF_TRUSTED_ORIGINS = [
    'https://mantis.yourdomain.com',
    'https://www.mantis.yourdomain.com',
]

# Security headers
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_BROWSER_XSS_FILTER = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = 'DENY'

Generate a new secret key:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Configure Static and Media Files

Ensure paths are correctly set:

STATIC_URL = '/static/'
STATIC_ROOT = '/opt/mantis/app/src/static_django'
MEDIA_URL = '/media/'
MEDIA_ROOT = '/opt/mantis/app/src/media'

Running the Development Server

For development and testing:

cd /opt/mantis/app/src
source venv/bin/activate
python manage.py runserver 0.0.0.0:8000

Access the application:

Django Admin: http://localhost:8000/admin
API: http://localhost:8000/api/
Frontend (if running dev server): http://localhost:5173

The development server is not suitable for production. Use Gunicorn or uWSGI with Nginx for production deployments.

Production Deployment

Using Gunicorn + Nginx

Install Gunicorn

source /opt/mantis/app/src/venv/bin/activate
pip install gunicorn

Create Gunicorn Service

Create /etc/systemd/system/mantis.service:

[Unit]
Description=Mantis Gunicorn Service
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=notify
User=www-data
Group=www-data
WorkingDirectory=/opt/mantis/app/src
Environment="PATH=/opt/mantis/app/src/venv/bin"
ExecStart=/opt/mantis/app/src/venv/bin/gunicorn \
    --workers 4 \
    --bind unix:/opt/mantis/app/src/mantis.sock \
    --timeout 120 \
    --access-logfile /var/log/mantis/access.log \
    --error-logfile /var/log/mantis/error.log \
    peisol.wsgi:application

[Install]
WantedBy=multi-user.target

Create log directory:

sudo mkdir -p /var/log/mantis
sudo chown www-data:www-data /var/log/mantis

Install and Configure Nginx

Install Nginx:

sudo apt install -y nginx

Create /etc/nginx/sites-available/mantis:

upstream mantis_app {
    server unix:/opt/mantis/app/src/mantis.sock fail_timeout=0;
}

server {
    listen 80;
    server_name mantis.yourdomain.com www.mantis.yourdomain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name mantis.yourdomain.com www.mantis.yourdomain.com;

    # SSL certificates (configure with certbot)
    ssl_certificate /etc/letsencrypt/live/mantis.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mantis.yourdomain.com/privkey.pem;

    client_max_body_size 100M;

    # Static files
    location /static/ {
        alias /opt/mantis/app/src/static_django/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Media files
    location /media/ {
        alias /opt/mantis/app/src/media/;
        expires 7d;
    }

    # Application
    location / {
        proxy_pass http://mantis_app;
        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;
        proxy_redirect off;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/mantis /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Start Services

Enable and start the Mantis service:

sudo systemctl daemon-reload
sudo systemctl enable mantis
sudo systemctl start mantis

Check status:

sudo systemctl status mantis

Restart Services (When Needed)

After code updates:

sudo systemctl daemon-reload
sudo systemctl restart mantis.service
sudo systemctl restart nginx

Or as a single command:

sudo systemctl daemon-reload && \
sudo systemctl restart mantis.service && \
sudo systemctl restart nginx

Data Management

Exporting Data

Export all application data to JSON:

python manage.py dumpdata \
  --natural-foreign \
  --natural-primary \
  --exclude auth.permission \
  --exclude contenttypes \
  --exclude admin.logentry \
  > data.json

Importing Data

Import data from JSON:

python manage.py loaddata data.json

For verbose output:

./manage.py loaddata /path/to/data.json -v 3

Always backup your database before importing data:

pg_dump -U mantis_user mantis > backup_$(date +%Y%m%d_%H%M%S).sql

Backup and Maintenance

Database Backup

# Full backup
pg_dump -U mantis_user -h localhost mantis > mantis_backup_$(date +%Y%m%d).sql

# Compressed backup
pg_dump -U mantis_user -h localhost mantis | gzip > mantis_backup_$(date +%Y%m%d).sql.gz

Database Restore

# From SQL file
psql -U mantis_user -h localhost mantis < mantis_backup.sql

# From compressed file
gunzip -c mantis_backup.sql.gz | psql -U mantis_user -h localhost mantis

Automated Backups

Create a cron job for daily backups:

sudo crontab -e

Add:

# Daily database backup at 2 AM
0 2 * * * pg_dump -U mantis_user mantis | gzip > /backup/mantis_$(date +\%Y\%m\%d).sql.gz

# Clean backups older than 30 days
0 3 * * * find /backup -name "mantis_*.sql.gz" -mtime +30 -delete

Troubleshooting

Database Issues

Connection Refused

Check PostgreSQL is running:

sudo systemctl status postgresql
sudo systemctl restart postgresql

Verify connection settings in common/secrets.py

Permission Denied

Grant necessary permissions:

GRANT ALL PRIVILEGES ON DATABASE mantis TO mantis_user;
GRANT ALL ON SCHEMA public TO mantis_user;

Migration Conflicts

Reset migrations (development only):

./manage.py migrate accounts zero
./manage.py migrate accounts

Service Issues

Gunicorn Won't Start

Check logs:

sudo journalctl -u mantis.service -n 50 --no-pager
tail -f /var/log/mantis/error.log

Common issues:

Virtual environment path incorrect
Socket permission problems
Python import errors

502 Bad Gateway

Verify Gunicorn is running:

sudo systemctl status mantis

Check socket file exists:

ls -la /opt/mantis/app/src/mantis.sock

Check Nginx error logs:

sudo tail -f /var/log/nginx/error.log

Static Files Not Loading

Ensure collectstatic was run:

./manage.py collectstatic --noinput

Verify Nginx configuration points to correct path.Check file permissions:

ls -la /opt/mantis/app/src/static_django/

Performance Issues

Slow Response Times

Increase Gunicorn workers:

# In mantis.service
--workers 8  # 2-4 x CPU cores

Enable database query logging to identify slow queries.

Memory Usage High

Reduce Gunicorn workers or add worker timeouts.Check for memory leaks in custom code.Consider using worker class gevent for I/O bound applications.

Security Checklist

Before deploying to production:

Next Steps

Project Management

Learn how to create and manage projects.

API Documentation

Explore the REST API endpoints and authentication.

Equipment Tracking

Set up and track equipment and resources.

User Guides

Complete guides for using Mantis effectively.

Get Started

Core Features

User Guides

Installation Guide

Installation Guide

System Requirements

Software Requirements

Hardware Requirements

Installation Steps

1. System Preparation

2. Database Setup

3. Application Setup

4. Django Migrations

5. Frontend Setup

6. Static Files Collection

Environment Configuration

Development Environment

Production Environment

Running the Development Server

Production Deployment

Using Gunicorn + Nginx

Data Management

Exporting Data

Importing Data

Backup and Maintenance

Database Backup

Database Restore

Automated Backups

Troubleshooting

Database Issues

Service Issues

Performance Issues

Security Checklist

Next Steps

Project Management

API Documentation

Equipment Tracking

User Guides

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

​Installation Guide

​System Requirements

​Software Requirements

​Hardware Requirements

​Installation Steps

​1. System Preparation

​2. Database Setup

​3. Application Setup

​4. Django Migrations

​5. Frontend Setup

​6. Static Files Collection

​Environment Configuration

​Development Environment

​Production Environment

​Running the Development Server

​Production Deployment

​Using Gunicorn + Nginx

​Data Management

​Exporting Data

​Importing Data

​Backup and Maintenance

​Database Backup

​Database Restore

​Automated Backups

​Troubleshooting

​Database Issues

​Service Issues

​Performance Issues

​Security Checklist

​Next Steps

Project Management

API Documentation

Equipment Tracking

User Guides

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Software Requirements

Hardware Requirements

Installation Steps

1. System Preparation

2. Database Setup

3. Application Setup

4. Django Migrations

5. Frontend Setup

6. Static Files Collection

Environment Configuration

Development Environment

Production Environment

Running the Development Server

Production Deployment

Using Gunicorn + Nginx

Data Management

Exporting Data

Importing Data

Backup and Maintenance

Database Backup

Database Restore

Automated Backups

Troubleshooting

Database Issues

Service Issues

Performance Issues

Security Checklist

Next Steps