LightForgeDB

An open-source project by DarkTeamDev.

At DarkTeamDev, we frequently found ourselves bogged down by the setup and management of local databases for every new project or feature branch. To solve this, we created LightForgeDB.

It's our solution for a self-hosted, web-based management UI for PostgreSQL that streamlines development workflows. It acts as a lightweight "factory" for provisioning isolated databases on a central server, allowing our team to get up and running in seconds without managing local PostgreSQL instances.

Core Features

• On-the-Fly Database Provisioning: Create new databases and dedicated user roles with unique credentials through a simple web interface.
• User & Tenancy Management: A complete authentication system where each user manages their own set of databases.
• Powerful Database Explorer: A built-in web UI for exploring schemas, viewing table data, and executing raw SQL queries, powered by the Monaco Editor.
• Full CRUD on Table Data: Directly add, edit, and delete rows from the data viewer.
• Admin Dashboard: Superusers can manage all users, view their databases, manage balances, and send notifications.
• Secure by Design: Encrypts provisioned database credentials at rest and uses JWT for API authentication.
• Lightweight & Self-Hosted: Run it on your own infrastructure with minimal setup.

Tech Stack

• Backend: FastAPI, Python 3.12
• Database ORM: SQLAlchemy 2.0 (async) with Alembic for migrations
• Database Driver: asyncpg
• Frontend: Vanilla JavaScript (ES6+), jQuery, Chart.js
• UI/Styling: Material 3 Design principles, custom CSS
• Deployment: Docker

Getting Started

Follow these instructions to get a local development environment running.

Prerequisites

• Git
• Python 3.12+
• Access to a running PostgreSQL server (v14+ recommended). This will be the "management" database where LightForgeDB creates new user databases.
• Docker (for containerized deployment)

1. Installation

First, clone the repository and navigate into the project directory.

git clone https://github.com/DarkTeamDev/LightForgeDB.git
cd LightForgeDB

Next, create and activate a Python virtual environment.

# For Unix/macOS
python3 -m venv venv
source venv/bin/activate

# For Windows
python -m venv venv
.\venv\Scripts\activate

Install the required Python packages.

pip install -r requirements.txt

2. Configuration

The application is configured using environment variables. We've included an example file; copy it to create your own local configuration.

cp .env.example .env

Now, open the .env file and set the values for your environment.

# --- Application Settings ---
# Generate a secure secret key. You can use: openssl rand -hex 32
APP_SECRET_KEY="your_super_secret_key_here"
ACCESS_TOKEN_EXPIRE_MINUTES=60
BCRYPT_ROUNDS=12 # Use 12+ for production, can be lowered for tests

# --- DATABASE CONFIGURATION ---

# 1. This is the database for LightForgeDB's own metadata (users, db instances, etc.)
#    It's recommended to create a dedicated database for this.
APP_DATABASE_URL="postgresql+asyncpg://app_user:app_password@your_db_host:5432/lightforgedb_meta"

# 2. This is the DSN for the privileged PostgreSQL user.
#    This user MUST have CREATEDB and CREATEROLE permissions.
#    It's used by the application to provision new databases and roles for your users.
PG_MANAGEMENT_DSN_ASYNCPG="postgresql://your_superuser:your_superuser_password@your_db_host:5432/postgres"

3. Database Migrations

LightForgeDB needs its own tables in the metadata database. Before running the app, apply the database migrations using Alembic.

First, ensure the sqlalchemy.url in alembic.ini points to your metadata database (use the same URL as APP_DATABASE_URL but without the +asyncpg part).

# alembic.ini
...
sqlalchemy.url = postgresql://app_user:app_password@your_db_host:5432/lightforgedb_meta
...

Then, run the migrations:

alembic upgrade head

4. Running the Development Server

You can now start the application.

python run.py

The application will be available at http://127.0.0.1:8000. Note: The first user who registers will automatically become a superuser.

Docker Deployment

A Dockerfile is included for easy containerization.

1. Build the Image

From the project root, run the build command:

docker build -t lightforgedb-app:latest .

2. Run the Container

Use the following command to run the application in a detached container. Replace the placeholder values with your actual configuration.

docker run -d \
    --name lightforgedb-instance \
    -p 8810:8810 \
    -e APP_SECRET_KEY="your_super_secret_key_here" \
    -e ACCESS_TOKEN_EXPIRE_MINUTES="60" \
    -e BCRYPT_ROUNDS="12" \
    -e APP_DATABASE_URL="postgresql+asyncpg://app_user:app_password@your_db_host:5432/lightforgedb_meta" \
    -e PG_MANAGEMENT_DSN_ASYNCPG="postgresql://your_superuser:your_superuser_password@your_db_host:5432/postgres" \
    --restart unless-stopped \
    lightforgedb-app:latest

The application will now be running on port 8810 of your host machine.

Project Structure

LightForgeDB/
├── lightforgedb/
│   ├── api/          # FastAPI routers and dependencies
│   ├── core/         # Core logic (config, security, db manager)
│   ├── db/           # SQLAlchemy models, session, and Alembic migrations
│   ├── schemas/      # Pydantic schemas for data validation
│   ├── services/     # Business logic services
│   ├── main.py       # Main FastAPI application entry point
│   └── ...
├── static/           # All frontend assets (CSS, JS, icons)
├── templates/        # Jinja2 templates for serving the SPA shells
├── alembic.ini       # Alembic configuration
├── Dockerfile        # Container definition
├── requirements.txt  # Python dependencies
└── run.py            # Development server runner

Contributing

LightForgeDB is an open-source project by DarkTeamDev, and we welcome contributions from the community. Whether it's a bug report, a feature suggestion, or a pull request, we'd love to hear from you.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

License

Copyright (c) 2025 DarkTeamDev.

This project is licensed under the MIT License. See the LICENSE file for details.