Saltar a contenido

Quick Start Guide

Get the Laboratory Management System running on your local machine in 5 minutes.

Prerequisites

System Requirements: - 4GB RAM minimum (8GB recommended) - 10GB free disk space - macOS, Windows, or Linux

Quick Setup

1. Clone the Repository

git clone <your-repository-url> laboratory-system
cd laboratory-system

2. Copy Environment File

cp .env.example .env

The default .env file is pre-configured for development. No changes needed to get started!

3. Build and Start Services

# Build Docker images and start all services
docker compose up --build

First-time build takes 5-10 minutes depending on your internet connection. Docker will download images and install dependencies.

You'll see logs from all services. Wait for the message: Listening at: http://0.0.0.0:8000

4. Setup Database (in a new terminal)

Open a second terminal in the same directory:

# Run database migrations
make manage ARGS="migrate"

# Create a superuser account
make manage ARGS="createsuperuser"

Follow the prompts to create your admin account.

5. Access the Application

Open your browser and navigate to:

http://localhost:8000

You should see the laboratory system home page!

Next Steps

Explore the System

Load Test Data

# Create test users for all roles (script is standalone Python, not shell input)
docker compose exec -T web python3 /app/simple_test_data.py
# Or from host if Python/Django env matches the container:
# python simple_test_data.py

Do not use make manage ARGS="shell" < simple_test_data.py: shell opens an interactive REPL inside Docker and expects a TTY; piping a file triggers the input device is not a TTY.

This creates: - Veterinarian: vet@example.com / testpass123 - Histopathologist: histo@example.com / testpass123 - Lab Staff: staff@example.com / testpass123 (is_staff=True, órdenes de trabajo) - Lab Tech: lab_tech1@adlab.local / lab123 (is_staff=True si se creó con simple_test_data.py)

See Test Credentials for complete list.

Run Tests

# Run the full test suite
make test

# Run specific app tests
make manage ARGS="test accounts"
make manage ARGS="test protocols"

# Run specific test file
make manage ARGS="test protocols.tests.ProtocolTestCase"

Check Code Quality

# Lint Python code
make lint

# Format Python code
make format

# Run all quality checks
make quality

Common Development Tasks

View Logs

# View all service logs
docker compose logs -f

# View specific service
docker compose logs -f web
docker compose logs -f postgres
docker compose logs -f worker

Stop the Application

# Stop all services (Ctrl+C in the terminal running docker compose up)
# OR
docker compose down

Start Again

# Start services (much faster after first build)
docker compose up

Reset Database

# Stop services
docker compose down

# Remove database volume
docker volume rm laboratory-system_postgres

# Start and migrate
docker compose up -d
make manage ARGS="migrate"
make manage ARGS="createsuperuser"

Access Django Shell

# Python shell with Django
make manage ARGS="shell"

# Access PostgreSQL
make psql

# Access Redis CLI
make redis-cli

Update Dependencies

# Check outdated packages
make uv-outdated
make yarn-outdated

# After updating pyproject.toml or package.json
make deps-install

# Rebuild containers
docker compose up --build

Development Workflow

Typical Development Session

# 1. Start services
docker compose up

# 2. (In another terminal) Make code changes
vim src/accounts/views.py

# 3. Changes auto-reload (no restart needed for most Python code)
# Watch the logs to see the reload

# 4. Run tests for what you changed
make manage ARGS="test accounts.test_views"

# 5. Check code quality before committing
make quality

Database Migrations

# After changing models
make manage ARGS="makemigrations"

# Apply migrations
make manage ARGS="migrate"

# View migration SQL (optional)
make manage ARGS="sqlmigrate accounts 0001"

# Show migration status
make manage ARGS="showmigrations"

Troubleshooting

Port 8000 Already in Use

# Find what's using port 8000
lsof -i :8000

# Kill the process or change port in .env
DOCKER_WEB_PORT_FORWARD=8001

Permission Denied Errors

# Check UID/GID in .env (Linux users)
id  # Check your uid:gid

# Update .env if needed
UID=1000
GID=1000

# Rebuild
docker compose down
docker compose up --build

Database Connection Errors

# Check if postgres is running
docker compose ps postgres

# View postgres logs
docker compose logs postgres

# Restart postgres
docker compose restart postgres

Changes Not Reflecting

# For Python code changes - should auto-reload
# Check logs for "Reloading..."

# For static files (CSS/JS)
# Rebuild assets
docker compose restart assets

# For Docker/environment changes
# Full rebuild
docker compose down
docker compose up --build

Tests Failing

# Clean up test database
make test-cleanup

# Run tests again
make test

# Run with verbose output
make manage ARGS="test --verbosity=2"

Development Tools

Django Debug Toolbar

Enabled automatically in development: - Visit any page - Click the debug toolbar on the right side - View SQL queries, templates, cache hits, etc.

Interactive Debugger

Use breakpoint() in your Python code:

def my_view(request):
    breakpoint()  # Execution will pause here
    # ... rest of code

Then interact in the terminal where docker compose up is running.

Watch Mode for Frontend Assets

Assets (CSS/JS) automatically rebuild when you edit them. Check the assets service logs:

docker compose logs -f assets

What's Running?

After docker compose up, you have:

  • web: Django application server (port 8000)
  • postgres: PostgreSQL database (port 5432)
  • redis: Redis cache (port 6379)
  • worker: Celery worker (background tasks)
  • beat: Celery beat scheduler
  • assets: esbuild + TailwindCSS watcher

Next Steps

Now that you're up and running:

  1. Understand the workflow: Read Laboratory Workflow
  2. Explore test data: Check Test Credentials
  3. Learn the architecture: Read CLAUDE.md
  4. Configure for your needs: See Configuration
  5. Deploy to production: See Deployment Guide

Getting Help

← Back to Setup Documentation | Documentation Home