Quick Start Guide

Get Mantis up and running quickly with this streamlined setup guide covering prerequisites, installation, and creating your first project.

Quick Start Guide

Get Mantis running on your local machine in minutes. This guide covers the essential steps to set up a development environment.

Prerequisites

Before you begin, ensure you have the following installed:

Python 3.x

Python 3.8 or higher required for Django 4.2

PostgreSQL

PostgreSQL 12 or higher for database storage

Node.js

Node.js 20.19.0+ or 22.12.0+ for frontend development

Git

For cloning the repository

Quick Setup

1. Clone the Repository

   Clone the Mantis source code to your local machine:

   git clone <repository-url>
   cd mantis
   
2. Configure Database

   Create a PostgreSQL database for Mantis:

   # Access PostgreSQL
   psql -U postgres
   
   # Create database
   CREATE DATABASE mantis;
   CREATE USER mantis_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE mantis TO mantis_user;
   

   Configure your database connection in app/src/common/secrets.py:

   DATABASES = {
       'DEVELOPMENT': {
           "ENGINE": "django.db.backends.postgresql",
           'NAME': 'mantis',
           'USER': 'mantis_user',
           'PASSWORD': 'your_password',
           'HOST': 'localhost',
           'PORT': '5432',
       }
   }
   
   DEFAULT_DB = {
       'default': DATABASES['DEVELOPMENT']
   }
   
3. Set Up Backend

   Navigate to the Django project directory and run migrations:

   cd app/src
   
   # Create migrations for core apps
   python manage.py makemigrations accounts
   python manage.py makemigrations equipment projects
   
   # Apply migrations
   python manage.py migrate
   
   # Seed initial data
   python manage.py sowseed
   
   # Populate audit history
   python manage.py populate_history --auto
   

   The sowseed command populates the database with initial data required for system operation.

4. Create Superuser

   Create an administrative user to access the Django admin:

   python manage.py createsuperuser
   

   Follow the prompts to enter:

   • Email address (used as username)
   • Password
   • Additional user information
5. Set Up Frontend

   Install and build the Vue.js frontend:

   cd app/client/mantis
   
   # Install dependencies
   npm install
   
   # Run development server
   npm run dev
   

   The frontend will be available at http://localhost:5173

   For production builds, use npm run build which will compile and copy assets to the Django static directories.

6. Start Django Development Server

   Return to the Django directory and start the backend server:

   cd ../../src
   python manage.py runserver
   

   The Django API and admin interface will be available at http://localhost:8000

Creating Your First Project

Once Mantis is running, you can create your first project through either the Django admin interface or the API.

Via Django Admin

1. Access Admin Interface

   Navigate to http://localhost:8000/admin and log in with your superuser credentials.

2. Create a Partner

   Before creating a project, you need a partner (client):

   1. Go to Projects → Partners
   2. Click Add Partner
   3. Fill in the partner details (name, contact info, etc.)
   4. Click Save
3. Create a Project

   Now create your first project:

   1. Go to Projects → Projects
   2. Click Add Project
   3. Select the partner you just created
   4. Fill in project details:
      • Location (campamento)
      • Cardinal point
      • Contact name and phone
      • Start date
   5. Click Save
4. Allocate Resources

   Add resources to your project:

   1. From the project detail page, scroll to Project Resource Items
   2. Click Add another Project Resource Item
   3. Select a resource item (equipment or service)
   4. Configure:
      • Resource type (EQUIPO or SERVICIO)
      • Cost
      • Maintenance frequency
      • Operation dates
   5. Click Save

Via API

You can also create projects programmatically using the REST API:

# First, obtain an authentication token (if using token auth)
curl -X POST http://localhost:8000/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "password": "your_password"}'

# Create a project
curl -X POST http://localhost:8000/api/projects/projects/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your_token>" \
  -d '{
    "partner_id": 1,
    "location": "Campo Norte",
    "cardinal_point": "NORTE",
    "contact_name": "Juan Pérez",
    "contact_phone": "0999123456",
    "start_date": "2026-03-04"
  }'

Make sure to configure CSRF trusted origins in settings.py if you’re accessing the API from a different domain.

Verify Your Installation

Confirm everything is working correctly:

Check Django Admin

• Navigate to http://localhost:8000/admin
• Log in successfully
• View the Grappelli-enhanced interface
• Access Projects, Equipment, and Accounts sections

Check API Endpoints

Test API availability:

curl http://localhost:8000/api/

You should receive a JSON response with available endpoints.

Check Frontend

• Navigate to http://localhost:5173
• Verify the Vue.js application loads
• Check that assets load correctly
• Test navigation between pages

Check Database

Verify database connectivity:

python manage.py dbshell

This should open a PostgreSQL prompt. You can run:

\dt  -- List all tables
SELECT * FROM accounts_customusermodel;  -- Check users

Common Issues

Database Connection Error

If you see “could not connect to server”:

1. Verify PostgreSQL is running: sudo systemctl status postgresql
2. Check database credentials in common/secrets.py
3. Ensure the database exists: psql -U postgres -l
4. Verify host and port settings

Migration Errors

If migrations fail:

1. Reset migrations (development only):
   python manage.py migrate --fake accounts zero
   python manage.py migrate accounts
   
2. Check for circular dependencies in models
3. Ensure all apps are listed in INSTALLED_APPS

Frontend Build Errors

If npm run build fails:

1. Clear node_modules: rm -rf node_modules package-lock.json
2. Reinstall: npm install
3. Check Node.js version: node --version (should be 20.19.0+)
4. Clear Vite cache: rm -rf node_modules/.vite

Static Files Not Loading

If static files don’t appear:

1. Collect static files:
   python manage.py collectstatic
   
2. Check STATIC_ROOT and STATIC_URL in settings
3. Verify STATICFILES_DIRS configuration

Next Steps

Now that Mantis is running, explore these topics:

Installation Guide

Learn about production deployment and advanced configuration.

API Reference

Explore the complete REST API documentation.

Project Features

Learn about project management capabilities.

User Guides

Deep dive into project workflows and resource allocation.

Need Help?

For detailed installation instructions, including production deployment, environment configuration, and troubleshooting, see the Installation Guide.