# Local Deployment

> This guide walks you through running ContextForge on your local machine using a virtual environment or directly via Python.

- Skill: `tools-only/local-deployment` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/local-deployment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/local-deployment/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/local-deployment

---

# 🐍 Local Deployment

This guide walks you through running ContextForge on your local machine using a virtual environment or directly via Python.

---

## 🚀 One-Liner Setup

The easiest way to start the server in development mode:

```bash
make venv install-dev serve
```

This does the following:

1. Creates a `.venv/` virtual environment
2. Installs all dependencies (including dev tools)
3. Launches **Gunicorn** on `http://localhost:4444`

---

## 🧪 Development Mode with Live Reload

If you want auto-reload on code changes:

```bash
make dev        # hot-reload (Uvicorn) on :8000
# or:
./run.sh --reload --log debug
```

> Ensure your `.env` file includes:
>
> ```env
> DEV_MODE=true
> RELOAD=true
> DEBUG=true
> ```

---

## 🗄 Database Configuration

By default, ContextForge uses SQLite for simplicity. You can configure alternative databases via the `DATABASE_URL` environment variable:

=== "SQLite (Default)"
    ```bash
    # .env file
    DATABASE_URL=sqlite:///./mcp.db
    ```

=== "MariaDB"
    ```bash
    # .env file
    DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp
    ```

    !!! info "MariaDB Setup"
        Install and configure MariaDB server:
        ```bash
        # Ubuntu/Debian
        sudo apt update && sudo apt install mariadb-server

        # Create database and user
        sudo mariadb -e "CREATE DATABASE mcp;"
        sudo mariadb -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
        sudo mariadb -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
        sudo mariadb -e "FLUSH PRIVILEGES;"
        ```

=== "MySQL"
    ```bash
    # .env file
    DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp
    ```

    !!! info "MySQL Setup"
        Install and configure MySQL server:
        ```bash
        # Ubuntu/Debian
        sudo apt update && sudo apt install mysql-server

        # Create database and user
        sudo mysql -e "CREATE DATABASE mcp;"
        sudo mysql -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
        sudo mysql -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
        sudo mysql -e "FLUSH PRIVILEGES;"
        ```

=== "PostgreSQL"
    ```bash
    # .env file
    DATABASE_URL=postgresql+psycopg://postgres:changeme@localhost:5432/mcp
    ```

!!! tip "MariaDB & MySQL Full Compatibility"
    MariaDB and MySQL are **fully supported** with:

    - **36+ database tables** working perfectly with MariaDB 10.6+ and MySQL 8.0+
    - All **VARCHAR length issues** resolved for MariaDB/MySQL compatibility
    - Complete feature parity with SQLite and PostgreSQL

---

## 🧪 Health Test

```bash
curl http://localhost:4444/health
```

Expected output:

```json
{"status": "healthy"}
```

---

## 🔐 Admin UI

Visit [http://localhost:4444/admin](http://localhost:4444/admin) and login using your `PLATFORM_ADMIN_EMAIL` and `PLATFORM_ADMIN_PASSWORD` from `.env`.

---

## 🔁 Quick JWT Setup

```bash
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token -u admin@example.com)
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools
```