docker

Docker Setup

This guide is for running ChordMini with Docker Desktop or Docker Compose.

What You Need

1. Docker Desktop installed and open.
2. A copy of this repository on your computer.
3. Firebase web app values for the basic app setup.

Note

Docker Desktop must be running before the commands below will work. If Docker is closed, commands such as docker compose up may fail with a message about not being able to connect to the Docker daemon.

Files Used Here

• ../docker-compose.prod.yml - current published Docker Hub images, useful when you download only the production compose file.
• docker-compose.yml - current published Docker Hub images, used from this repository.
• docker-compose.dev.yml - builds the frontend and backend images locally from this repository.
• ../Dockerfile - frontend image build.
• ../python_backend/Dockerfile - backend image build.
• ../.env.docker.example - template for Docker environment variables.

Step 1: Make Your Docker Env File

From the repository root:

cp .env.docker.example .env.docker

Open .env.docker and fill in the Firebase values:

NEXT_PUBLIC_FIREBASE_API_KEY=...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=...
NEXT_PUBLIC_FIREBASE_PROJECT_ID=...
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=...
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=...
NEXT_PUBLIC_FIREBASE_APP_ID=...

Optional keys can stay blank until you need those features:

NEXT_PUBLIC_YOUTUBE_API_KEY=
MUSIC_AI_API_KEY=
GEMINI_API_KEY=
GENIUS_API_KEY=

Note

Lines that start with NEXT_PUBLIC_ are safe to send to the browser. Keys without NEXT_PUBLIC_, such as GEMINI_API_KEY, are server-only and should not be shared publicly.

Step 2: Choose How To Start

Option A: Pull Published Images

This is the shortest path. It pulls the current ptnghia/chordminiapp-frontend:latest and ptnghia/chordminiapp-backend:latest images from Docker Hub.

docker compose -f docker/docker-compose.yml --env-file .env.docker pull
docker compose -f docker/docker-compose.yml --env-file .env.docker up

Open http://localhost:3000.

To stop the app, press Ctrl+C. Then run:

docker compose -f docker/docker-compose.yml --env-file .env.docker down

Note

The published images are built for linux/amd64. The compose file includes that platform setting so Docker Desktop can run them on Apple Silicon with emulation. If your computer feels slow with the published images, use Option B to build native local images instead.

Option B: Build Locally

Use this option on Intel Macs, Windows PCs, Linux PCs, or whenever pulling the published images fails.

docker compose -f docker/docker-compose.dev.yml --env-file .env.docker build
docker compose -f docker/docker-compose.dev.yml --env-file .env.docker up

Open http://localhost:3000.

To stop the app, press Ctrl+C. Then run:

docker compose -f docker/docker-compose.dev.yml --env-file .env.docker down

Note

The first local build can take a while because the backend installs Python audio libraries and downloads model files.

Docker Desktop GUI Steps

If you prefer to click through Docker Desktop:

1. Open Docker Desktop and wait until it says the engine is running.
2. Open the repository folder in Terminal, PowerShell, or the Docker Desktop terminal.
3. Create .env.docker using Step 1 above.
4. Run either Option A or Option B above.
5. In Docker Desktop, open Containers to see chordmini-frontend, chordmini-backend, and, for local builds, chordmini-redis.
6. Use the stop/start buttons in Docker Desktop after the containers have been created.

Note

Avoid running the frontend and backend images one by one from the Images tab. Docker Compose starts them on the same network and passes the app settings from .env.docker, which is the part that makes the services find each other.

Quick Checks

Frontend:

curl http://localhost:3000/api/health

Backend:

curl http://localhost:8080/health

Both should return a small healthy response.

Common Problems

Docker Cannot Connect To The Daemon

Open Docker Desktop first, wait until it finishes starting, and run the command again.

Port Already In Use

The app uses these ports:

• 3000 for the web app
• 8080 for the Python backend
• 6379 for Redis in the local-build setup

Stop the other program using the port, or change the left side of the port mapping in the compose file. For example, 3001:3000 makes the app available at http://localhost:3001.

Published Image Does Not Match Your Computer

Use the local-build setup:

docker compose -f docker/docker-compose.dev.yml --env-file .env.docker build
docker compose -f docker/docker-compose.dev.yml --env-file .env.docker up

Reset Everything Docker Created For This App

For the published-image setup:

docker compose -f docker/docker-compose.yml --env-file .env.docker down --volumes

For the local-build setup:

docker compose -f docker/docker-compose.dev.yml --env-file .env.docker down --volumes