Docker Local Setup Guide
This guide explains how to run Shrutik completely with Docker on your local machine, including all the configuration changes needed to switch from local development to Docker.
Quick Docker Setup
Prerequisites
-
Docker 20.10+
-
Docker Compose 2.0+
-
Git
1. Clone the Repo
git clone https://github.com/Onuronon-lab/Shrutik.git
cd Shrutik
# Switch to the deployment-dev branch
git fetch origin
git switch deployment-dev
2. Configure Environment for Docker
Use the Docker-specific environment file:
cp .env.example .env
Make sure the DATABASE_URL is correct in .env file
DATABASE_URL=postgresql://postgres:password@postgres:5432/voice_collection
When running inside Docker, services communicate using their Docker Compose service names.
Available Environment Files:
.env.example- Template with all available options
3. Configure Frontend
cd frontend
cp .env.example .env
4. Start All Containers
Use this when running the app for the first time or after changing Dockerfiles, requirements.txt, or package.json:
docker compose up -d --build
Regular use (no changes)
For normal daily use, when the images are already built:
docker compose up -d
Check service status:
docker compose ps
5. Initialize the Database
Run migrations:
docker compose exec backend alembic upgrade head
Create admin user:
docker compose exec backend python scripts/create_admin.py --name "Admin" --email admin@example.com
6. Access the Application
-
Frontend → http://localhost:3000
-
API Docs → http://localhost:8000/docs
-
Health Check → http://localhost:8000/health
Configuration Changes Explained
Key Differences: Local vs Docker
| Component | Local Development | Docker |
|---|---|---|
| Database URL | localhost:5432 | postgres:5432 |
| Redis URL | localhost:6379 | redis:6379 |
| Frontend API URL | http://localhost:8000 | http://localhost:8000 |
| File Paths | ./uploads | /app/uploads |
Development Workflow
Start services
docker compose up -d
Stop everything
docker compose down
Stop AND remove volumes (fresh reset)
docker compose down -v
View logs
docker compose logs -f
Specific service logs:
docker compose logs -f backend
Rebuild after changing requirements
docker compose build --no-cache
docker compose up -d
Shell into a container
docker compose exec backend bash
Check backend health
curl http://localhost:8000/health
Database Management
Run migrations:
docker compose exec backend alembic upgrade head
Auto-generate migration:
docker compose exec backend alembic revision --autogenerate -m "message"
Connect to PostgreSQL:
docker compose exec postgres psql -U postgres -d voice_collection
Redis Debugging
Test Redis:
docker compose exec redis redis-cli ping
Restart Redis:
docker compose restart redis
Troubleshooting
Port in use
Check:
sudo lsof -i :6379
sudo lsof -i :5432
Kill process:
sudo kill <pid>
Backend not starting
docker compose logs backend
Frontend not loading
docker compose logs frontend
docker compose build frontend --no-cache
docker compose up -d frontend