chapter-organizer/DEPLOYMENT.md

Docker Deployment Guide

Authentication Configuration for Production

The application supports two methods for configuring authentication credentials in Docker:

Option 1: Volume-Mounted JSON File (Recommended)

This approach allows you to edit credentials without rebuilding the container.

Steps:

1. Generate Password Hashes (on your development machine):

   # Run the app locally and navigate to:
   https://localhost:<port>/dev/hash-password?password=YourPassword
   

2. Create auth-secrets.json on your Docker host:

   cp auth-secrets.example.json auth-secrets.json
   

3. Edit auth-secrets.json and replace the placeholder hashes:

   {
     "Authentication": {
       "Users": [
         {
           "Email": "admin@example.com",
           "PasswordHash": "$2a$11$actual.hash.here",
           "Role": "Administrator",
           "DisplayName": "Administrator"
         }
       ]
     }
   }
   

4. Mount the file in Docker Compose:

   volumes:
     - ./auth-secrets.json:/app/secrets/auth-secrets.json:ro
   

5. Update credentials: Simply edit auth-secrets.json on the host and restart the container:

   docker-compose restart webapp
   

Security Note: Set proper file permissions on the host:

chmod 600 auth-secrets.json

---

Option 2: Environment Variables

This approach is useful for container orchestration platforms (Kubernetes, Docker Swarm, etc.).

Docker Compose Example:

environment:
  - TSA_Authentication__Users__0__Email=admin@example.com
  - TSA_Authentication__Users__0__PasswordHash=$2a$11$hash...
  - TSA_Authentication__Users__0__Role=Administrator
  - TSA_Authentication__Users__0__DisplayName=Administrator
  - TSA_Authentication__Users__1__Email=advisor@example.com
  - TSA_Authentication__Users__1__PasswordHash=$2a$11$hash...
  - TSA_Authentication__Users__1__Role=Advisor
  - TSA_Authentication__Users__1__DisplayName=Chapter Advisor

Docker Run Example:

docker run -d \
  -p 8080:8080 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e TSA_Authentication__Users__0__Email=admin@example.com \
  -e TSA_Authentication__Users__0__PasswordHash='$2a$11$hash...' \
  -e TSA_Authentication__Users__0__Role=Administrator \
  -e TSA_Authentication__Users__0__DisplayName=Administrator \
  tsa-chapter-organizer:latest

Kubernetes Secret Example:

apiVersion: v1
kind: Secret
metadata:
  name: tsa-auth-secrets
type: Opaque
stringData:
  TSA_Authentication__Users__0__Email: "admin@example.com"
  TSA_Authentication__Users__0__PasswordHash: "$2a$11$hash..."
  TSA_Authentication__Users__0__Role: "Administrator"
  TSA_Authentication__Users__0__DisplayName: "Administrator"

---

Building and Running

Publish to Docker Registry (Recommended)

Use the provided PowerShell script to build and publish the Docker image:

.\publish-docker.ps1

Options:

• -Tag "v1.0.0" - Specify a custom tag (default: "latest")
• -Registry "docker-registry.kolpacksoftware.com" - Specify registry URL
• -ImageName "tsa-chapter-organizer" - Specify image name
• -BuildConfiguration "Release" - Specify build configuration

Examples:

# Publish with default settings (latest tag)
.\publish-docker.ps1

# Publish with a version tag
.\publish-docker.ps1 -Tag "v1.0.0"

# Publish with custom registry
.\publish-docker.ps1 -Tag "latest" -Registry "my-registry.com"

Build the Docker Image (Manual)

If you prefer to build manually:

cd WebApp
docker build -t tsa-chapter-organizer:latest .

Or from the root directory:

docker build -f WebApp/Dockerfile -t tsa-chapter-organizer:latest .

Run with Docker Compose

# Copy and customize the example
cp docker-compose.example.yml docker-compose.yml

# Edit auth-secrets.json with your credentials
cp auth-secrets.example.json auth-secrets.json
# (Edit the file and replace hashes)

# Start the container
docker-compose up -d

# View logs
docker-compose logs -f webapp

Access the Application

• HTTP: http://localhost:8080
• HTTPS: https://localhost:8081 (if configured)

---

Data Persistence (SQLite + Backups)

The app stores its SQLite database and runtime config under Data/ (capital D) relative to the content root:

Path in container	Purpose
/app/Data/app.db	Live SQLite database
/app/Data/appsettings.json	Chapter settings overrides (e.g. CompetitionYear)
/app/Data/backups/pre-rollover-*.db	Automatic backups created by New Year Rollover

Docker volume mount must use capital Data:

volumes:
  - ./data:/app/Data

On Linux, ./data:/app/data is a different path and will not persist the database or rollover backups. After a correct mount, host files appear under ./data/ (for example ./data/app.db and ./data/backups/).

Ensure the container user can write to the mounted directory (the image runs as a non-root APP_UID). If directory creation for backups/ fails, year rollover aborts before changing data.

For the rollover workflow itself, see docs/instructions/year-rollover.md.

---

Managing Users

Adding a New User

With Volume-Mounted File:

1. Edit auth-secrets.json on the host
2. Add new user entry to the Users array
3. Restart the container: docker-compose restart webapp

With Environment Variables:

1. Add new environment variables (increment the index number)
2. Recreate the container: docker-compose up -d

Changing a Password

1. Generate new hash using the dev endpoint (on local dev machine)
2. Update the PasswordHash value in your configuration
3. Restart/recreate the container

Removing a User

1. Remove the user entry from your configuration
2. Restart/recreate the container

---

Security Considerations

1. File Permissions:

   chmod 600 auth-secrets.json
   chown root:root auth-secrets.json
   

2. Never Commit Secrets: Add to .gitignore:

   auth-secrets.json
   docker-compose.yml
   

3. Use HTTPS in Production: Configure SSL/TLS certificates

4. Backup Credentials: Store encrypted backups of auth-secrets.json

5. Password Rotation: Periodically regenerate password hashes

6. Monitor Access: Review application logs for failed login attempts:

   docker-compose logs webapp | grep "Failed login"
   

---

Troubleshooting

Container Won't Start

Check logs:

docker-compose logs webapp

Can't Login

1. Verify auth-secrets.json is properly mounted:

   docker exec tsa-app ls -la /app/secrets/
   

2. Check if the file is being loaded:

   docker-compose logs webapp | grep "secrets"
   

3. Verify JSON syntax:

   cat auth-secrets.json | jq .
   

Forgot Admin Password

1. Generate a new password hash locally
2. Update auth-secrets.json on the host
3. Restart the container

---

Example: Complete Setup

# 1. Generate password hashes locally
# Navigate to: https://localhost:5001/dev/hash-password?password=MySecurePass123

# 2. Create secrets file
cat > auth-secrets.json <<EOF
{
  "Authentication": {
    "Users": [
      {
        "Email": "admin@myschool.edu",
        "PasswordHash": "$2a$11$paste_hash_here",
        "Role": "Administrator",
        "DisplayName": "TSA Admin"
      }
    ]
  }
}
EOF

# 3. Set permissions
chmod 600 auth-secrets.json

# 4. Create docker-compose.yml
cp docker-compose.example.yml docker-compose.yml

# 5. Start the application
docker-compose up -d

# 6. Check it's running
docker-compose ps
curl http://localhost:8080

# 7. Login
# Navigate to http://localhost:8080/login
# Use: admin@myschool.edu / MySecurePass123

---

Production Deployment Checklist

• Generated secure password hashes
• Created auth-secrets.json with production credentials
• Set file permissions to 600
• Configured HTTPS/SSL certificates
• Updated ASPNETCORE_URLS for production domain
• Configured volume for database persistence as ./data:/app/Data (capital D)
• Verified app.db appears on the host under ./data/ after first run
• Removed development endpoints (already done in code)
• Set up log monitoring
• Confirmed year-rollover backups write to ./data/backups/ (see docs/instructions/year-rollover.md)
• Tested login with all user roles
• Tested rate limiting (5 failed attempts)
• Documented admin password securely
• Added auth-secrets.json to .gitignore