Development Environment Setup

This document provides instructions for establishing development environments for the OCTAVIUS system, including both containerized and local deployment approaches.

Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows (with WSL2 or Docker Desktop)
• Memory: 16GB RAM minimum (32GB recommended)
• Disk Space: 50GB available storage
• Internet Connection: Required for dependency installation and Docker image downloads

Containerized Deployment (Docker Compose)

Installation Requirements

1. Docker: Install from docker.com
2. Docker Compose: Typically included with Docker Desktop; verify installation:

   docker --version
   docker-compose --version
   

Quick Start

1. Clone or navigate to the repository root
2. Generate MongoDB security keyfile:

   cd mongo
   openssl rand -base64 756 > mongo-keyfile
   chmod 400 mongo-keyfile
   cd ../docker
   

3. Start services:

   docker-compose -f docker-compose.yml up --build
   

4. Services will initialize and be accessible at:
   • UI: http://localhost:3000
   • API: http://localhost:8443
   • MongoDB: localhost:27017 (internal connection)

Service Architecture

The Docker Compose configuration orchestrates three containers:

Service	Technology	Port	Purpose
ui	Node.js + React	3000	User interface development server
api	Node.js + Express	8443	REST API server
mongo	MongoDB	27017	Document database (internal)

Cleanup

To stop services and remove containers:

docker-compose down

To remove volumes (database data):

docker-compose down -v

Local Development (Non-Containerized)

Prerequisites

• Node.js: Version 20.x or higher
• npm: Version 6.x or higher
• MongoDB: Version 8 or higher
• Git: For version control

API Server Setup

1. Install Node.js and npm from nodejs.org

2. Navigate to API directory:

   cd api
   

3. Install dependencies:

   npm install
   

4. Configure environment variables:
   • Create .env file in the api/ directory
   • Required variables:

     MONGODB_URI=mongodb://localhost:27017/octavius
     JWT_SECRET=your_secret_key_here
     NODE_ENV=development
     

5. Start the API server:

   npm run start
   

   Or for development with auto-reload:

   npm run dev
   

The API will be accessible at http://localhost:8443 (or configured port).

MongoDB Setup

1. Install MongoDB:
   • macOS: brew install mongodb-community
   • Ubuntu/Debian: Follow MongoDB installation guide
   • Windows: Download from mongodb.com
2. Start MongoDB service:

   # macOS
   brew services start mongodb-community
      
   # Linux
   sudo systemctl start mongod
      
   # Windows
   net start MongoDB
   

3. Restore development data (optional):

   mongorestore -u username -p password docker/octavius-db
   

4. Create initial user (if database is empty):

   mongo octavius
   > db.users.insertOne({email: "admin@example.com", password: "hashed", role: "admin"})
   

UI Development Server Setup

1. Navigate to UI directory:

   cd ui
   

2. Install dependencies:

   npm install --legacy-peer-deps
   

3. Configure environment variables:
   • Create .env file in the ui/ directory
   • Required variables:

     REACT_APP_API_URL=http://localhost:8443
     

4. Start development server:

   npm start
   

The UI will be accessible at http://localhost:3000 and automatically open in your browser.

Environment Configuration

API Environment Variables

Variable	Purpose	Example
MONGODB_URI	Database connection string	mongodb://localhost:27017/octavius
JWT_SECRET	Authentication secret key	(contact administrator)
NODE_ENV	Deployment environment	development, production
API_PORT	Server port	8443
LOG_LEVEL	Logging verbosity	debug, info, error

UI Environment Variables

Variable	Purpose	Example
REACT_APP_API_URL	API endpoint	http://localhost:8443
REACT_APP_ENV	Environment	development

Secrets Management

Production deployments require secure credential management:

1. Store sensitive values (database passwords, API keys) in environment files
2. Never commit secrets to version control
3. Add environment files to .gitignore:

   .env
   .env.local
   .env.*.secret
   

4. Distribute secret values through secure channels only

Development Workflow

Integrated Development Steps

1. Terminal 1 – Python API:

   cd api
   npm run start
   

2. Terminal 2 – React UI:

   cd ui
   npm start
   

3. Terminal 3 – MongoDB (if running locally):

   mongod
   

Hot Reload and Debugging

• UI Changes: Automatically reload in browser
• API Changes: Stop server, restart, or use nodemon:

  npm install -g nodemon
  nodemon server.js
  

• Database: Changes persist to MongoDB; restart server to pick up schema changes

Troubleshooting

Connection Issues

Problem: UI cannot reach API

Solution:

• Verify API is running on configured port
• Check REACT_APP_API_URL environment variable
• Ensure firewall allows connections

MongoDB Connection Failures

Problem: MongoDB connection timeout

Solution:

• Verify MongoDB service is running: mongosh (or mongo for older versions)
• Check connection URI in environment variables
• Ensure database credentials are correct

Port Already in Use

Problem: “Port X is already in use”

Solution:

# Find process using port (macOS/Linux)
lsof -i :8443

# Change port in environment configuration
API_PORT=8444 npm start

Additional Resources

• Docker Documentation
• Node.js Documentation
• React Documentation
• MongoDB Manual
• Express.js Guide