Quick Start Guide¶

Get the New Hires Reporting System running in 15 minutes.

Overview¶

This guide will walk you through deploying the system for the first time. You'll set up AWS Bedrock credentials, configure environment variables, pull Docker images, and start all services.

Before You Begin¶

Ensure you have completed all Prerequisites:

✅ Docker and Docker Compose installed
✅ AWS account with Bedrock access enabled
✅ IAM credentials with bedrock:InvokeModel permission
✅ Ports 8000 and 8080 available

Step-by-Step Deployment¶

Step 1: Get AWS Bedrock Credentials¶

If you haven't set up AWS Bedrock yet, follow the AWS Bedrock Setup Guide to:

Enable AWS Bedrock in us-east-1
Request access to Claude Sonnet 4.5 model
Create IAM user with Bedrock permissions
Get your Access Key ID and Secret Access Key

Quick summary:

# Test your AWS credentials
aws sts get-caller-identity

# Verify Bedrock access
aws bedrock list-foundation-models --region us-east-1

Step 2: Create Deployment Directory¶

# Create deployment directory
mkdir -p /opt/newhires-reporting
cd /opt/newhires-reporting

# Create backups directory for database backups
mkdir backups

Step 3: Create Environment File¶

Create a .env file with your configuration:

# Create .env file
cat > .env << 'EOF'
###############################
# Docker Image Configuration
###############################
# Get IMAGE_TAG from your development team
IMAGE_TAG=sha-a85b396

###############################
# AWS Bedrock Configuration
###############################
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1

###############################
# Database Configuration
###############################
POSTGRES_PASSWORD=ChangeThisToSecurePassword123!

###############################
# Optional: Worker Configuration
###############################
# MAX_CONCURRENT_BEDROCK_CALLS=2
# POLL_INTERVAL=5
# MAX_AI_ATTEMPTS=5
EOF

# Set secure permissions
chmod 600 .env

Replace Example Values

Make sure to replace: - AKIAIOSFODNN7EXAMPLE with your actual AWS Access Key ID - wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY with your actual AWS Secret Access Key - ChangeThisToSecurePassword123! with a strong database password - sha-a85b396 with the IMAGE_TAG provided by your development team

Verify your .env file:

# Check file exists and has correct permissions
ls -l .env

# Verify required variables are set (don't use EXAMPLE values)
grep -E "AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|IMAGE_TAG" .env

Step 4: Get docker-compose.prod.yml¶

You should receive docker-compose.prod.yml from your development team. Place it in your deployment directory.

# Verify file exists
ls -l docker-compose.prod.yml

# Your directory should now look like:
# /opt/newhires-reporting/
# ├── docker-compose.prod.yml
# ├── .env
# └── backups/

Step 5: Authenticate to AWS ECR¶

Authenticate Docker to pull images from AWS ECR:

# Install AWS CLI if needed
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Configure AWS CLI (if not already done)
aws configure
# Enter your AWS Access Key ID
# Enter your AWS Secret Access Key
# Region: us-east-1
# Output format: json

# Authenticate Docker to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  878796852397.dkr.ecr.us-east-1.amazonaws.com

Expected output: Login Succeeded

ECR Credentials Expire

ECR authentication tokens expire after 12 hours. You'll need to re-run the aws ecr get-login-password command if you get authentication errors later.

Step 6: Pull Docker Images¶

Download all application images:

docker-compose -f docker-compose.prod.yml pull

Expected output:

Pulling db       ... done
Pulling backend  ... done
Pulling workers  ... done
Pulling frontend ... done

This downloads approximately 1.3 GB of images.

Step 7: Start Services¶

Start all services in detached mode:

docker-compose -f docker-compose.prod.yml up -d

Expected output:

Creating network "newhires-reporting_default" ... done
Creating volume "newhires-reporting_postgres-data" ... done
Creating newhires-db       ... done
Creating newhires-backend  ... done
Creating newhires-workers  ... done
Creating newhires-frontend ... done

Verify all services started:

docker ps

You should see 4 containers running: - newhires-db - newhires-backend - newhires-workers - newhires-frontend

Step 8: Initialize Database¶

Run database migrations to create tables:

# Wait 10 seconds for database to be ready
sleep 10

# Run migrations
docker exec newhires-backend alembic upgrade head

Expected output:

INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade  -> abcdef, Initial migration

Step 9: Verify Deployment¶

Check that all services are healthy:

# Check backend health
curl http://localhost:8000/health
# Expected: {"status":"healthy"}

# Check frontend is accessible
curl -I http://localhost:8080
# Expected: HTTP/1.1 200 OK

# Check database connection
docker exec newhires-db psql -U newhires -d newhires -c "SELECT 1;"
# Expected: Shows "1" result

# Check worker is running
docker logs newhires-workers --tail=20
# Expected: "INFO: Worker polling for jobs..."

Step 10: Access the Application¶

Web Interface: Open your browser to:

http://localhost:8080

Or if accessing from another machine:

http://your-server-ip:8080

API Documentation: Browse API docs at:

http://localhost:8000/docs

What's Running?¶

After successful deployment, you have:

Service	Port	Description	Access
Frontend	8080	React web interface	http://localhost:8080
Backend API	8000	REST API	http://localhost:8000
Workers	-	Background AI processors	(no UI)
PostgreSQL	5432	Database	(internal only)

Quick Operations¶

View Logs¶

# All services
docker-compose -f docker-compose.prod.yml logs -f

# Specific service
docker-compose -f docker-compose.prod.yml logs -f workers
docker-compose -f docker-compose.prod.yml logs -f backend

Restart Services¶

# Restart all
docker-compose -f docker-compose.prod.yml restart

# Restart specific service
docker-compose -f docker-compose.prod.yml restart workers

Stop Services¶

# Stop all (preserves data)
docker-compose -f docker-compose.prod.yml down

# Start again
docker-compose -f docker-compose.prod.yml up -d

Check Service Status¶

# View container status
docker-compose -f docker-compose.prod.yml ps

# View resource usage
docker stats

Troubleshooting¶

Services Won't Start¶

# Check logs for errors
docker-compose -f docker-compose.prod.yml logs

# Common issues:
# 1. Missing .env file
ls -la .env

# 2. Invalid AWS credentials
grep AWS_ACCESS_KEY_ID .env

# 3. Port conflicts
sudo netstat -tlnp | grep -E '8000|8080'

"Cannot pull image" Error¶

Cause: ECR authentication expired or invalid

Solution:

# Re-authenticate to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  878796852397.dkr.ecr.us-east-1.amazonaws.com

# Try pull again
docker-compose -f docker-compose.prod.yml pull

Workers Not Processing Jobs¶

# Check worker logs
docker logs newhires-workers --tail=50

# Look for AWS errors like:
# "Access Denied" -> Check IAM permissions
# "Could not connect to endpoint" -> Check AWS region
# "Model not found" -> Check Bedrock model access enabled

# Verify AWS credentials in container
docker exec newhires-workers env | grep AWS

Database Connection Errors¶

# Check database is running
docker ps | grep newhires-db

# Check database logs
docker logs newhires-db

# Test connection
docker exec newhires-db psql -U newhires -d newhires -c "SELECT 1;"

Backend API Returns Errors¶

# Check backend logs
docker logs newhires-backend --tail=50

# Verify backend can reach database
docker exec newhires-backend env | grep DATABASE_URL

# Restart backend
docker-compose -f docker-compose.prod.yml restart backend

Can't Access Web Interface¶

If accessing from same machine:

# Check frontend is running
docker ps | grep newhires-frontend

# Check frontend logs
docker logs newhires-frontend

# Test locally
curl http://localhost:8080

If accessing from different machine:

# Check firewall allows port 8080
sudo ufw status | grep 8080

# Allow port if needed
sudo ufw allow 8080/tcp

Next Steps¶

Now that your system is running:

Configure Environment - Fine-tune worker settings
Setup Monitoring - Monitor your deployment
Optional: HTTPS Setup - Add reverse proxy and SSL
Learn to Use - Start validating files

Daily Operations¶

Start Services (After Reboot)¶

cd /opt/newhires-reporting
docker-compose -f docker-compose.prod.yml up -d

Check Everything is Working¶

# Quick health check
curl http://localhost:8000/health && \
curl -I http://localhost:8080 && \
echo "All services healthy!"

Backup Database¶

# Manual backup
docker exec newhires-db pg_dump -U newhires newhires > \
  backups/backup_$(date +%Y%m%d_%H%M%S).sql

Update to New Version¶

# Update IMAGE_TAG in .env file
nano .env

# Re-authenticate to ECR (if expired)
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  878796852397.dkr.ecr.us-east-1.amazonaws.com

# Pull new images
docker-compose -f docker-compose.prod.yml pull

# Restart with new images
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d

# Run migrations
docker exec newhires-backend alembic upgrade head

Getting Help¶

If you encounter issues:

Check logs: docker-compose -f docker-compose.prod.yml logs
Review troubleshooting: Common Issues
Check AWS setup: AWS Bedrock Setup
Read full deployment guide: Docker Compose Deployment

Success!¶

Your New Hires Reporting System is now running and ready to process files with AI-powered corrections! 🚀

Access the web interface at http://localhost:8080 to start uploading files.