Run Badge Box Locally

Want to run Badge Box on your own computer? Follow this guide to set up everything locally. No advanced technical skills required — just follow step by step.

Prerequisites

Before you start, make sure you have these installed on your computer:

Required Software

• Python 3.10 or higher — Download Python
• Node.js 18 or higher — Download Node.js
• A Nostr private key (nsec) OR a browser extension like Alby or nos2x

Not sure if you have these installed?

Open your terminal (Command Prompt on Windows, Terminal on Mac/Linux) and type:

python --version
node --version

If you see version numbers, you're good to go!

Step 1: Get the Code

First, download the Badge Box code to your computer.

Open Your Terminal

All commands below should be typed in your terminal. On Mac, search for "Terminal". On Windows, search for "Command Prompt" or "PowerShell".

git clone https://github.com/rinbal/Badges_GUI.git
cd Badges_GUI

Don't have Git?

You can also download the ZIP file from GitHub and extract it.

Step 2: Install the Backend

The backend is the server that handles all the badge logic. First, create a virtual environment to keep dependencies isolated.

cd backend
python -m venv venv

Activate the virtual environment:

Mac / Linux

source venv/bin/activate

Windows

venv\Scripts\activate

Now install the dependencies:

pip install -r requirements.txt
pip install -r ../requirements.txt

What does this do?

python -m venv venv creates an isolated Python environment so Badge Box's packages don't interfere with your system Python. pip install then downloads and installs all the Python packages that Badge Box needs to run inside that environment.

Step 3: Install the Frontend

The frontend is what you see in your browser.

cd ../frontend
npm install

What does this do?

npm install downloads all the JavaScript packages needed for the user interface. This might take a minute or two.

Step 4: Start the Servers

You need to run two servers at the same time. This means opening two terminal windows.

Terminal 1: Start the Backend

Make sure the virtual environment is activated (you should see (venv) in your terminal prompt), then start the server:

cd backend
source venv/bin/activate   # On Windows: venv\Scripts\activate
uvicorn app.main:app --reload --port 8000

Backend Running

You should see output like:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Started reloader process

Terminal 2: Start the Frontend

Open a new terminal window and run:

cd frontend
npm run dev

Frontend Running

You should see output like:

VITE v5.x.x  ready
➜  Local:   http://localhost:5173/

Step 5: Open Badge Box

Open your web browser and go to:

http://localhost:5173

That's it! Badge Box is now running on your computer.

Stopping the Servers

To stop the servers, go to each terminal window and press Ctrl + C (or Cmd + C on Mac).

Troubleshooting

Port Already in Use

Another app is using port 8000 or 5173. Close other servers or change the port number.

Command Not Found

Python or Node.js isn't installed. Download them from the links above.

Need more help?

Check out the Troubleshooting Guide or open an issue on GitHub.