Docker Setup

The fastest way to run Straktur. One command gives you everything.

Requirements

You need Docker installed on your machine. Choose one:

Quick Start

# Clone the repository (use your purchased repo URL)
git clone <your-repo-url>
cd straktur

# Create your .env from the template (required — Docker won't start without it)
cp .env.example .env

# Start everything
docker compose up

First run takes 2-5 minutes (downloading images, installing dependencies). After that, starts in ~30 seconds.

Once ready, open http://localhost:3000

That's it! You now have a fully working app.

What's Running

MinIO credentials: minioadmin / minioadmin

Demo Data

To make your start easier, we've prepared demo data that shows you what a real app built with Straktur looks like.

Explore it to see how everything works together - navigation patterns, UI components, data tables, forms, file uploads, and all the features you get out of the box. It's the best way to understand Straktur before building your own features.

What's included:

• 44 companies with logos and details
• 70+ contacts linked to companies
• Activities, relationships, and file attachments
• All dictionary values (statuses, industries, regions)

Starting fresh

Want to start with an empty database instead? Set SEED_DEMO_DATA: "false" in docker-compose.yml and run:

docker compose down -v
docker compose up

Common Commands

Start the app

docker compose up

Starts everything and shows logs in your terminal. You'll see what's happening in real-time, but your terminal is busy. Press Ctrl+C to stop.

docker compose up -d

Starts in background - your terminal stays free. Use this when you don't need to watch logs.

View logs

docker compose logs -f app

Shows app logs in real-time. Useful when you started in background or need to debug why something isn't working.

Stop the app

docker compose down

Stops all containers. Your data (database, files) is preserved - next docker compose up will have everything as you left it.

Full reset

docker compose down -v
docker compose up

Warning: The -v flag deletes ALL data - database, uploaded files, everything. Use this only when you want to start completely fresh.

Running on Different Ports

Need to run alongside another instance, or have port conflicts? All ports are configurable via environment variables.

Add them to the .env you created in Quick Start:

# .env
APP_PORT=3001
DB_PORT=5434
MINIO_PORT=9002
MINIO_CONSOLE_PORT=9003
MAILPIT_SMTP_PORT=1026
MAILPIT_UI_PORT=8081

Then start normally:

docker compose up

You only need to set the ports that conflict — all have sensible defaults. To try a port without editing anything, prefix the command instead: APP_PORT=3001 docker compose up.

What .env does and doesn't control

Some variables are set directly in docker-compose.yml and take precedence over your .env — editing them there has no effect on the Docker setup:

This is deliberate: those values must describe the container network, not your host.

The dev convenience values are fixed in docker-compose.yml too — BETTER_AUTH_SECRET, SEED_USER_*, SEED_ORG_*, SEED_DEMO_DATA, ALLOW_DB_SEED / ALLOW_DB_RESET. To change the seeded user or organization, edit them there rather than in .env.

Everything else works normally from .env: the port variables above, APP_MODE, NEXT_PUBLIC_EXAMPLES_MODE, the OAuth credentials, and the optional SMTP / Resend / Supabase settings.

Development vs Production

By default, Docker runs in development mode with hot reload and devtools.

Development (default)

docker compose up

• Hot reload enabled
• TanStack Query and Next.js devtools visible
• Faster startup (no build step)

Production mode

APP_MODE=production docker compose up

Or set in .env:

APP_MODE=production

Production mode:

• Builds the app first (npm run build)
• Runs optimized next start instead of next dev
• No devtools icons
• Better performance, closer to real deployment

Troubleshooting

env file .env not found

Compose exits immediately, before starting any container. The .env file is missing:

cp .env.example .env

Can't log in

Make sure you're using the correct credentials:

• Email: test@local.dev
• Password: testingpassword

If it still doesn't work, the seed might have failed. Check logs and try resetting:

docker compose down -v
docker compose up

App shows errors or blank page

Check what's happening in the logs:

docker compose logs -f app

Look for error messages - they usually tell you what's wrong.

Code changes not visible

If your changes aren't showing up, restart the app container:

docker compose restart app

Database not responding

Check if PostgreSQL is running:

docker compose ps
docker compose logs db

Wait for "database system is ready to accept connections" message. If it's not starting, try a full reset:

docker compose down -v
docker compose up

Next Steps

• Project Structure - Understand the codebase
• Add Your First Feature - Build something