Backend Setup

Set up local development environment for Go server and Python CLI

Prerequisites

Install the required tools for backend development:

Go 1.21+

golang.org/dl

Python 3.11+

python.org/downloads

Git

git-scm.com

AWS CLI

aws.amazon.com/cli

Quick Start

1. Clone Repository

   Clone the SuperBox backend repository:

   git clone https://github.com/areebahmeddd/superbox.ai.git
   cd superbox.ai
   
2. Create Virtual Environment

   Create and activate a Python virtual environment:

   Windows (PowerShell):

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

   macOS/Linux:

   python3 -m venv .venv
   source .venv/bin/activate
   
3. Install Python CLI

   Install SuperBox CLI with dependencies:

   python -m pip install -e .[cli]
   

   Optional (dev tools):

   python -m pip install -e .[dev]
   
4. Configure Environment

   Create .env file in your working directory:

   # SuperBox API
   SUPERBOX_API_URL=http://localhost:8000/api/v1
   
   # AWS (required for S3-backed registry)
   AWS_REGION=ap-south-1
   AWS_ACCESS_KEY_ID=your_aws_access_key
   AWS_SECRET_ACCESS_KEY=your_aws_secret_key
   S3_BUCKET_NAME=your-bucket
   WEBSOCKET_URL=wss://api-gateway-id.execute-api.region.amazonaws.com/production
   
   # Scanners (required for superbox push)
   SONAR_TOKEN=your_sonar_token
   SONAR_ORGANIZATION=your_org
   GITGUARDIAN_API_KEY=your_gitguardian_key
   
   # Payments
   RAZORPAY_KEY_ID=your_razorpay_key_id
   RAZORPAY_KEY_SECRET=your_razorpay_secret
   

   Never commit .env to version control. Keep credentials secure.

5. Run Go Server

   Navigate to server directory and run:

   From src/superbox/server:

   cd src/superbox/server
   go run .
   

   Or build and run:

   go build -o server.exe .
   .\server.exe
   

   Server will be available at:

   • Health: http://127.0.0.1:8000/health
   • API: http://127.0.0.1:8000/api/v1

Quick Start - Python CLI

1. Clone CLI Repository

   git clone https://github.com/areebahmeddd/SuperBox-CLI.git
   cd SuperBox-CLI
   
2. Create Virtual Environment

   Using venv
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
3. Install Dependencies

   pip install -r requirements.txt
   

   Or install in development mode:

   pip install -e ".[dev]"
   

   Development mode includes testing, linting, and formatting tools.

Using the CLI

After setup, verify CLI works:

superbox --help

Initialize a project:

superbox init

Authenticate (if needed):

superbox auth login

Troubleshooting

Missing .env

Ensure .env exists in your working directory with required AWS, Scanner, and Payment credentials.

AWS Permissions

Verify IAM credentials allow GetObject/PutObject for the S3 bucket.

Sonar Scanner

Install sonar-scanner CLI and set SONAR_TOKEN and SONAR_ORGANIZATION in .env.

ggshield/Bandit

Install these tools (ggshield, bandit) if running security scans via superbox push.

Next Steps

CLI Commands

Learn all CLI commands

API Reference

Explore HTTP API endpoints

Architecture

Understand system design

Deployment

Deploy to production

For complete setup instructions, visit https://superbox.1mindlabs.org/docs