Skip to main content

Deployment Guide

Overview​

This document provides deployment instructions for the Secure Controlled Guns and Ammunition Inventory Management System (SCGAIMS).

The guide covers:

  • Environment preparation
  • Source code retrieval
  • Virtual environment configuration
  • Dependency installation
  • Database configuration
  • Auth0 configuration
  • Environment variable setup
  • Application startup
  • Verification procedures

The deployment process has been designed to support development, testing, and future production environments.

Prerequisites

Before deploying SCGAIMS, ensure the following requirements are available.

Software Requirements​

Python​

Python 3.12+

Verify installation:

python --version

Git​

Git

Verify installation:

git --version

PostgreSQL​

Database services are provided through:

Supabase PostgreSQL

No local PostgreSQL installation is required unless operating in a standalone environment.

Auth0 Account​

An Auth0 tenant is required for authentication services.

Required components include:

Tenant

API

Web Application

Roles

Permissions

Source Code Deployment

Clone Repository​

Retrieve the application source code from GitHub.

git clone https://github.com/dev-byte9sec/SCGAIMS.git

Change Directory​

cd SCGAIMS

Verify Repository Structure​

Expected structure:

SCGAIMS/

├── backend/
├── inventory/
├── docs/
├── manage.py
├── requirements.txt
├── .env.example
└── .gitignore

Virtual Environment Configuration

Create Virtual Environment​

python -m venv venv

Activate Virtual Environment​

Windows​

venv\Scripts\activate

Linux​

source venv/bin/activate

macOS​

source venv/bin/activate

Verification​

Successful activation displays:

(venv)

at the command prompt.

Dependency Installation

Install Dependencies​

pip install -r requirements.txt

Verify Installation​

pip list

Expected packages include:

Django

djangorestframework

psycopg2-binary

python-dotenv

authlib

Environment Variable Configuration

Create Environment File​

Copy:

.env.example

to:

.env

Windows​

copy .env.example .env

Linux/macOS​

cp .env.example .env

Configure Database Variables

Edit:

.env

Example:

DB_NAME=postgres
DB_USER=<database_user>
DB_PASSWORD=<database_password>
DB_HOST=<database_host>
DB_PORT=6543

Configure Auth0 Variables

Example:

AUTH0_CLIENT_ID=<client_id>

AUTH0_CLIENT_SECRET=<client_secret>

AUTH0_DOMAIN=<tenant_domain>

AUTH0_CALLBACK_URL=http://127.0.0.1:8000/callback

Supabase Database Configuration

Obtain Database Credentials​

Navigate to:

Supabase Dashboard
    →
Project Settings
    →
Database

Record Values​

Capture:

Host

Database Name

Database User

Password

Port

and update the:

.env

file accordingly.

Auth0 Configuration

Create API​

In Auth0 create:

SCGAIMS API

Example Identifier:

https://api.scgaims.online

Create Application​

Create:

SCGAIMS Web

Application Type:

Regular Web Application

Configure Callbacks​

Allowed Callback URLs:

http://127.0.0.1:8000/callback

https://scgaims.online/callback

Configure Logout URLs​

http://127.0.0.1:8000

https://scgaims.online

Configure Roles​

Create roles:

Administrator

Supervisor

Officer

Configure Permissions​

Example permissions:

issue:inventory

return:inventory

resolve:investigation

view:records

view:auditlogs

Database Migration

Generate Migrations​

python manage.py makemigrations

Apply Migrations​

python manage.py migrate

Expected Result​

Operations to perform:
Apply all migrations

OK

Create Administrative User

If administrators are managed locally:

python manage.py createsuperuser

Example​

Username:
admin

Email:
admin@scgaims.online

Password:
********

Running the Application

Start Development Server​

python manage.py runserver

Expected Result​

Starting development server at:

http://127.0.0.1:8000/

Deployment Validation

Application Validation​

Navigate to:

http://127.0.0.1:8000/

Verify:

Application Loads Successfully

Database Validation​

Verify:

Inventory Retrieval

Issue Records

Audit Logs

return expected results.

API Validation​

Execute API tests using Postman.

Test Endpoint​

GET /inventory/

Expected:

[
    {
        "id": 1,
        "item_name": "9mm Ammunition"
    }
]

Postman Validation

Import:

scgaims_API_Endpoints.postman_collection.json

Execute:

GET /inventory/

POST /issue-item/

POST /return-item/

GET /issue-records/

GET /audit-logs/

POST /resolve-investigation/

Expected Outcome​

All endpoints return successful responses.

Cloudflare Deployment

Domain​

scgaims.online

is managed through Cloudflare.

Cloudflare Services​

Configured services include:

DNS Hosting

DNS Management

Domain Resolution

Validation​

Confirm:

Domain Resolves Correctly

DNS Records Present

HTTPS Available

Microsoft 365 Integration

Purpose​

Microsoft 365 supports organizational services associated with the SCGAIMS domain.

Examples:

admin@scgaims.online

audit@scgaims.online

support@scgaims.online

Validation​

Verify:

Mail Flow

DNS Records

Domain Ownership

Common Troubleshooting

Database Connection Failure

Error​

password authentication failed

Resolution​

Verify:

DB_USER

DB_PASSWORD

DB_HOST

DB_PORT

inside:

.env

Missing Environment Variables

Error​

NoneType

or

Environment Variable Missing

Resolution​

Verify:

.env

exists and contains all required variables.

Migration Errors

Resolution​

Run:

python manage.py makemigrations
python manage.py migrate

Auth0 Authentication Issues

Resolution​

Verify:

Callback URLs

Logout URLs

Client ID

Client Secret

Tenant Domain

Security Considerations

Never Commit Secrets​

The following must never be committed to GitHub:

.env

Database Passwords

Auth0 Secrets

Access Tokens

Commit Instead​

.env.example

Git Verification​

Confirm secrets are ignored:

git status

Expected:

.env not listed

Production Considerations

Future production deployments should implement:

HTTPS Enforcement

MFA

Step-Up Authentication

GitHub Actions CI/CD

CodeQL Scanning

Dependabot

Security Monitoring

Deployment Checklist

Environment​

✅ Python Installed

✅ Virtual Environment Created

✅ Dependencies Installed

Database​

✅ Supabase Configured

✅ Database Variables Configured

✅ Migrations Applied

Authentication​

✅ Auth0 Tenant Created

✅ API Created

✅ Web Application Created

✅ Roles Configured

✅ Permissions Configured

SCGAIMS​

✅ Application Starts Successfully

✅ API Endpoints Respond

✅ Audit Logging Functional

✅ Inventory Operations Functional

Conclusion

This deployment guide provides the procedures required to successfully deploy and configure SCGAIMS within a development environment. By following the documented process for environment preparation, Supabase configuration, Auth0 integration, and application startup, administrators can deploy a functioning instance of SCGAIMS capable of supporting inventory accountability, discrepancy detection, investigation management, and audit logging for controlled firearms and ammunition inventories.