Deploying Fasten Health

Introduction

Fasten Health is a revolutionary self-hosted personal health record (PHR) platform that puts you in complete control of your medical data. Unlike traditional healthcare portals scattered across multiple providers, Fasten Health aggregates all your medical records, lab results, prescriptions, and health data into a single, secure, and private platform that you own and control.

Built with privacy and interoperability at its core, Fasten Health connects directly to healthcare providers through standardized APIs (FHIR, SMART on FHIR) to automatically import and sync your medical records from hospitals, clinics, labs, and insurance providers across the United States.

Key Features

Unified Medical Records - Aggregate health data from multiple providers into one dashboard
Automatic Sync - Connect to 25,000+ healthcare institutions via secure APIs
Complete Privacy - Your medical data never leaves your server
FHIR Compatible - Built on healthcare interoperability standards (FHIR R4)
Timeline View - Chronological view of all medical encounters, procedures, and medications
Lab Results Tracking - Monitor trends in lab values over time with charts
Medication Management - Track current medications, dosages, and prescriptions
Document Storage - Upload and organize medical documents, images, and reports
Insurance Claims - Track EOBs and insurance claims in one place
Provider Directory - Search and connect to healthcare providers
Family Support - Manage records for dependents and family members
Export Capabilities - Download your complete health record in standard formats

Why Deploy Fasten Health on Klutch.sh?

Deploying Fasten Health on Klutch.sh provides unparalleled advantages for managing sensitive medical data:

Maximum Privacy - HIPAA-grade security with your data on your infrastructure
No Third-Party Access - Unlike consumer health apps, your medical records never touch external servers
Instant Deployment - Automatic Dockerfile detection gets you running in minutes
Persistent Storage - Reliable storage for years of medical records and documents
HTTPS by Default - Bank-level encryption for all medical data transmission
Custom Domains - Professional, branded access to your health records
Automated Backups - Never lose critical medical information
Cost-Effective - Predictable pricing without per-user or per-record fees
Full Control - Complete ownership of your healthcare data infrastructure

Prerequisites

Before deploying Fasten Health on Klutch.sh, ensure you have:

A Klutch.sh account
Basic familiarity with Docker and environment variables
A PostgreSQL or SQLite database (we’ll cover PostgreSQL setup)
Healthcare provider credentials (for connecting to medical records)
Basic understanding of FHIR healthcare standards (helpful but not required)

Understanding Fasten Health Architecture

Fasten Health consists of several components:

Frontend - Angular-based web interface for managing health records
Backend API - Go-based API server handling FHIR operations and provider connections
Database - PostgreSQL or SQLite for storing aggregated health data
FHIR Cache - Local storage for medical records synced from providers
Background Jobs - Automated sync workers for pulling updates from connected providers

Preparing Your Repository

First, create a new repository for your Fasten Health deployment. The Dockerfile below sets up a production-ready Fasten Health instance.

Dockerfile

Create a Dockerfile in your repository root:

# Multi-stage build for Fasten Health
FROM golang:1.21-alpine AS backend-builder

# Install build dependencies
RUN apk add --no-cache git build-base nodejs npm

# Clone Fasten Health repository
WORKDIR /app
RUN git clone --depth 1 --branch main https://github.com/fastenhealth/fasten-onprem.git .

# Build backend
WORKDIR /app/backend
RUN go mod download
RUN CGO_ENABLED=1 GOOS=linux go build -o /app/fasten-server ./cmd/fasten

# Build frontend
WORKDIR /app/frontend
RUN npm ci --production=false
RUN npm run build -- --configuration production

# Production stage
FROM alpine:3.19

# Install runtime dependencies
RUN apk add --no-cache \
    ca-certificates \
    sqlite \
    postgresql-client \
    tzdata

# Create non-root user
RUN addgroup -g 1000 fasten && \
    adduser -D -u 1000 -G fasten fasten

# Create necessary directories
RUN mkdir -p /opt/fasten/config \
             /opt/fasten/db \
             /opt/fasten/cache \
             /opt/fasten/logs && \
    chown -R fasten:fasten /opt/fasten

# Copy built artifacts
COPY --from=backend-builder /app/fasten-server /usr/local/bin/fasten-server
COPY --from=backend-builder /app/frontend/dist /opt/fasten/web

# Switch to non-root user
USER fasten
WORKDIR /opt/fasten

# Environment variables with defaults
ENV FASTEN_PORT=8080 \
    FASTEN_DATABASE_TYPE=sqlite \
    FASTEN_DATABASE_LOCATION=/opt/fasten/db/fasten.db \
    FASTEN_JWT_ISSUER_KEY="" \
    FASTEN_CACHE_DIR=/opt/fasten/cache \
    FASTEN_LOG_LEVEL=INFO \
    FASTEN_WEB_SRC=/opt/fasten/web

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/api/health || exit 1

# Expose port
EXPOSE 8080

# Start Fasten Health server
CMD ["fasten-server", "start", "--config", "/opt/fasten/config"]

Configuration File (Optional)

While environment variables work for most configurations, you can create a config.yaml for advanced settings:

web:
  listen:
    port: 8080
    host: 0.0.0.0
  src:
    frontend:
      path: /opt/fasten/web

database:
  type: postgres # or sqlite
  location: "postgres://username:password@postgres-host:5432/fasten?sslmode=require"
  # For SQLite: /opt/fasten/db/fasten.db

jwt:
  issuer:
    key: "your-secret-jwt-key-min-32-chars"

cache:
  type: filesystem
  location: /opt/fasten/cache

log:
  level: INFO
  file: /opt/fasten/logs/fasten.log

sync:
  enabled: true
  interval: 24h # Sync with providers every 24 hours

Docker Compose for Local Development (Optional)

For local testing before deploying to Klutch.sh:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: fasten
      POSTGRES_USER: fasten
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U fasten"]
      interval: 10s
      timeout: 5s
      retries: 5

  fasten:
    build: .
    ports:
      - "8080:8080"
    environment:
      FASTEN_DATABASE_TYPE: postgres
      FASTEN_DATABASE_LOCATION: "postgres://fasten:changeme@postgres:5432/fasten?sslmode=disable"
      FASTEN_JWT_ISSUER_KEY: "your-development-secret-key-min-32-characters-long"
    volumes:
      - fasten_cache:/opt/fasten/cache
      - fasten_logs:/opt/fasten/logs
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  fasten_cache:
  fasten_logs:

Test locally:

docker-compose up -d

Access Fasten Health at http://localhost:8080

Environment Variables Reference

Fasten Health supports the following environment variables:

Database Configuration:

FASTEN_DATABASE_TYPE - Database type: postgres or sqlite (default: sqlite)
FASTEN_DATABASE_LOCATION - Database connection string or file path

Server Configuration:

FASTEN_PORT - HTTP server port (default: 8080)
FASTEN_WEB_SRC - Path to frontend static files (default: /opt/fasten/web)

Security Configuration:

FASTEN_JWT_ISSUER_KEY - Secret key for JWT tokens (min 32 characters, required)

Cache and Storage:

FASTEN_CACHE_DIR - Directory for FHIR cache storage (default: /opt/fasten/cache)

Logging:

FASTEN_LOG_LEVEL - Log level: DEBUG, INFO, WARN, ERROR (default: INFO)

Sync Configuration:

FASTEN_SYNC_ENABLED - Enable automatic provider sync (default: true)
FASTEN_SYNC_INTERVAL - Sync interval, e.g., 24h, 12h (default: 24h)

Deploying on Klutch.sh

Now that your repository is ready, let’s deploy Fasten Health to Klutch.sh.

Step 1: Set Up PostgreSQL Database (Recommended)

While Fasten Health supports SQLite, PostgreSQL is recommended for production deployments with better performance and concurrent access.

Deploy a PostgreSQL instance on Klutch.sh following the PostgreSQL deployment guide

Create a dedicated database for Fasten Health:

psql -h example-postgres.klutch.sh -p 8000 -U postgres
CREATE DATABASE fasten;
CREATE USER fasten WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE fasten TO fasten;

Note your connection string:

postgres://fasten:your-secure-password@example-postgres.klutch.sh:8000/fasten?sslmode=require

Step 2: Create a New App

Log in to your Klutch.sh dashboard
Navigate to your project or create a new one
Click "New App" and select "Deploy from GitHub"
Authorize Klutch.sh to access your GitHub repositories
Select the repository containing your Fasten Health Dockerfile
Klutch.sh will automatically detect the Dockerfile in your repository

Step 3: Configure Environment Variables

In the app configuration, navigate to the "Environment Variables" section
Add the following environment variables:
- FASTEN_DATABASE_TYPE = postgres
- FASTEN_DATABASE_LOCATION = postgres://fasten:your-secure-password@example-postgres.klutch.sh:8000/fasten?sslmode=require (mark as sensitive)
- FASTEN_JWT_ISSUER_KEY = Generate a secure random string (min 32 characters, mark as sensitive)
- FASTEN_PORT = 8080
- FASTEN_LOG_LEVEL = INFO
- FASTEN_SYNC_ENABLED = true
- FASTEN_SYNC_INTERVAL = 24h

Generate a secure JWT key:

openssl rand -base64 48

Step 4: Configure Traffic and Networking

In the "Traffic" section, select HTTP
Set the internal port to 8080 (matches FASTEN_PORT)
Klutch.sh will automatically provide HTTPS access via your app's URL

Step 5: Attach Persistent Volumes

Fasten Health needs persistent storage for cached medical records and logs.

Navigate to the "Volumes" section in your app configuration
Click "Add Volume" and configure:
- Mount Path: /opt/fasten/cache
- Size: 10 GB (adjust based on the number of providers and records you expect to sync)
Add a second volume for logs:
- Mount Path: /opt/fasten/logs
- Size: 2 GB
If using SQLite instead of PostgreSQL, add a volume for the database:
- Mount Path: /opt/fasten/db
- Size: 5 GB

Volume sizing recommendations:

Cache volume: 5-20 GB depending on the number of connected providers and years of medical history
Logs volume: 1-5 GB for application and sync logs
Database volume (SQLite only): 5-10 GB for health records

Step 6: Deploy the App

Review your configuration to ensure all settings are correct
Click "Deploy" to start the deployment
Klutch.sh will build your Docker image and deploy Fasten Health
Monitor the deployment logs for any errors
Once deployed, access your Fasten Health instance at https://your-app-name.klutch.sh

Initial Setup and Configuration

After deployment, complete the initial setup:

First-Time User Registration

Navigate to https://your-app-name.klutch.sh
You'll be presented with the Fasten Health welcome screen
Click "Create Account"
Enter your credentials:
- Username
- Email address
- Strong password (use a password manager)
Accept the privacy notice (your data stays on your server)
Click "Register"

Connecting Healthcare Providers

Once logged in, connect your healthcare providers to start importing medical records:

Click "Sources" in the navigation menu
Click "Add New Source"
Search for your healthcare provider (hospital, clinic, lab, insurance company)
Select the provider from the list of 25,000+ supported institutions
Click "Connect" and you'll be redirected to the provider's authorization page
Log in with your provider credentials and authorize Fasten Health to access your records
Once authorized, Fasten Health will automatically begin syncing your medical records
Repeat for each healthcare provider you want to connect

Dashboard Overview

After connecting providers, you’ll see:

Timeline - Chronological view of all medical encounters
Records - Complete list of medical records by type (labs, medications, procedures, etc.)
Medications - Current and past medications with dosage information
Conditions - Diagnosed conditions and their status
Procedures - Medical procedures and surgeries
Immunizations - Vaccination history
Labs - Lab results with trend charts

Usage Examples

Searching Medical Records

Fasten Health provides powerful search capabilities:

// The search functionality is built into the UI, but here's how the API works

// Search across all records
GET /api/secure/query/search?query=diabetes

// Filter by resource type
GET /api/secure/query/search?query=metformin&resourceType=MedicationRequest

// Search within a date range
GET /api/secure/query/search?query=A1C&from=2024-01-01&to=2024-12-31

Tracking Lab Results Over Time

Monitor trends in lab values:

Navigate to "Labs" in the main menu
Select a specific lab type (e.g., "Hemoglobin A1C")
View the trend chart showing values over time
Export data to CSV for external analysis

Medication Management

Track your medications:

Go to "Medications"
View active prescriptions with dosage and instructions
See medication history and when prescriptions were filled
Set reminders for medication refills (if configured)

Uploading Documents

Upload medical documents not available through provider APIs:

Click "Documents"
Click "Upload Document"
Select document type (imaging report, discharge summary, etc.)
Upload PDF, images, or other file formats
Add metadata (date, provider, notes)
Documents are stored securely in your cache volume

Exporting Your Health Record

Generate a complete export of your medical data:

Navigate to "Settings"
Click "Export Data"
Choose export format:
- FHIR Bundle - Standard JSON format (interoperable)
- PDF Summary - Human-readable summary report
- CSV - Spreadsheet format for data analysis
Click "Generate Export"
Download the generated file

API Access for Developers

Fasten Health provides a RESTful API for custom integrations:

# Authenticate and get JWT token
curl -X POST https://your-app-name.klutch.sh/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'

# Get patient summary
curl https://your-app-name.klutch.sh/api/secure/patient/summary \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# List all observations (lab results)
curl https://your-app-name.klutch.sh/api/secure/resource/fhir/Observation \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get specific medication request
curl https://your-app-name.klutch.sh/api/secure/resource/fhir/MedicationRequest/{id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Python Example: Analyzing Lab Results

import requests
import pandas as pd
from datetime import datetime

class FastenHealthClient:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.token = self._authenticate(username, password)

    def _authenticate(self, username, password):
        response = requests.post(
            f"{self.base_url}/api/auth/signin",
            json={"username": username, "password": password}
        )
        return response.json()["token"]

    def get_observations(self, code=None):
        headers = {"Authorization": f"Bearer {self.token}"}
        url = f"{self.base_url}/api/secure/resource/fhir/Observation"
        if code:
            url += f"?code={code}"
        response = requests.get(url, headers=headers)
        return response.json()

    def analyze_lab_trends(self, lab_code):
        observations = self.get_observations(code=lab_code)

        data = []
        for obs in observations.get("entry", []):
            resource = obs["resource"]
            date = resource.get("effectiveDateTime")
            value = resource.get("valueQuantity", {}).get("value")
            unit = resource.get("valueQuantity", {}).get("unit")

            if date and value:
                data.append({
                    "date": datetime.fromisoformat(date.replace("Z", "+00:00")),
                    "value": value,
                    "unit": unit
                })

        df = pd.DataFrame(data)
        df = df.sort_values("date")

        return df

# Usage
client = FastenHealthClient(
    "https://your-app-name.klutch.sh",
    "your-username",
    "your-password"
)

# Analyze Hemoglobin A1C trends
a1c_data = client.analyze_lab_trends("4548-4")  # LOINC code for A1C
print(a1c_data)

# Calculate statistics
print(f"Average A1C: {a1c_data['value'].mean():.2f}")
print(f"Latest A1C: {a1c_data.iloc[-1]['value']:.2f}")
print(f"Trend: {a1c_data['value'].diff().mean():.3f} per test")

Node.js Example: Medication Tracker

const axios = require('axios');

class FastenHealthClient {
  constructor(baseUrl, username, password) {
    this.baseUrl = baseUrl;
    this.token = null;
    this.authenticate(username, password);
  }

  async authenticate(username, password) {
    const response = await axios.post(`${this.baseUrl}/api/auth/signin`, {
      username,
      password
    });
    this.token = response.data.token;
  }

  getHeaders() {
    return {
      'Authorization': `Bearer ${this.token}`,
      'Content-Type': 'application/json'
    };
  }

  async getMedications() {
    const response = await axios.get(
      `${this.baseUrl}/api/secure/resource/fhir/MedicationRequest`,
      { headers: this.getHeaders() }
    );
    return response.data;
  }

  async getActiveMedications() {
    const medications = await this.getMedications();

    return medications.entry
      ?.filter(entry => entry.resource.status === 'active')
      .map(entry => ({
        name: entry.resource.medicationCodeableConcept?.text,
        dosage: entry.resource.dosageInstruction?.[0]?.text,
        authoredOn: entry.resource.authoredOn,
        prescriber: entry.resource.requester?.display
      })) || [];
  }

  async checkRefillNeeded(daysThreshold = 7) {
    const medications = await this.getMedications();
    const today = new Date();
    const refillNeeded = [];

    for (const entry of medications.entry || []) {
      const resource = entry.resource;
      const dispenseRequest = resource.dispenseRequest;

      if (dispenseRequest?.validityPeriod?.end) {
        const endDate = new Date(dispenseRequest.validityPeriod.end);
        const daysRemaining = Math.floor((endDate - today) / (1000 * 60 * 60 * 24));

        if (daysRemaining <= daysThreshold && daysRemaining >= 0) {
          refillNeeded.push({
            medication: resource.medicationCodeableConcept?.text,
            daysRemaining,
            prescriber: resource.requester?.display
          });
        }
      }
    }

    return refillNeeded;
  }
}

// Usage
(async () => {
  const client = new FastenHealthClient(
    'https://your-app-name.klutch.sh',
    'your-username',
    'your-password'
  );

  // Get active medications
  const activeMeds = await client.getActiveMedications();
  console.log('Active Medications:', activeMeds);

  // Check for medications needing refill
  const refillNeeded = await client.checkRefillNeeded(7);
  if (refillNeeded.length > 0) {
    console.log('Medications needing refill within 7 days:', refillNeeded);
  }
})();

Production Best Practices

Security Hardening

1. Strong Authentication

Use strong, unique passwords (minimum 16 characters)
Enable two-factor authentication if Fasten Health adds support in future releases

Rotate the JWT secret key periodically:

# Generate new JWT key
openssl rand -base64 48

# Update environment variable in Klutch.sh dashboard
# Users will need to re-authenticate after JWT key rotation

2. Database Security

Use PostgreSQL with strong passwords
Enable SSL/TLS for database connections (sslmode=require)
Regularly update PostgreSQL to patch security vulnerabilities
Restrict database access to only the Fasten Health app

3. Network Security

Always use HTTPS (Klutch.sh provides this automatically)
Consider using a custom domain with DNS-based access controls
Monitor access logs for suspicious activity

4. Data Privacy Compliance

While Fasten Health is designed for personal use, consider these practices:

Review connected provider permissions regularly
Audit data access logs periodically
Implement a data retention policy
Ensure backups are encrypted
Document your security procedures

Performance Optimization

1. Database Tuning

Configure PostgreSQL for optimal Fasten Health performance:

-- Recommended PostgreSQL settings for Fasten Health

-- Increase connection pool
ALTER SYSTEM SET max_connections = 100;

-- Optimize memory usage
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
ALTER SYSTEM SET work_mem = '16MB';
ALTER SYSTEM SET maintenance_work_mem = '128MB';

-- Improve query performance
ALTER SYSTEM SET random_page_cost = 1.1;
ALTER SYSTEM SET effective_io_concurrency = 200;

-- Enable query logging for debugging (disable in production)
ALTER SYSTEM SET log_statement = 'all';
ALTER SYSTEM SET log_duration = on;

-- Reload configuration
SELECT pg_reload_conf();

2. Cache Volume Optimization

Monitor cache volume usage regularly
Implement cache cleanup for old FHIR resources if needed
Consider increasing cache size if syncing many providers

3. Sync Optimization

Configure sync intervals based on your needs:

# Frequent updates for critical data
FASTEN_SYNC_INTERVAL=6h

# Standard daily sync
FASTEN_SYNC_INTERVAL=24h

# Weekly sync for historical data
FASTEN_SYNC_INTERVAL=168h

4. Resource Monitoring

Monitor Fasten Health resource usage:

# Check container resource usage
docker stats fasten-health

# Monitor disk usage
du -sh /opt/fasten/*

# Check database size
psql -h example-postgres.klutch.sh -p 8000 -U fasten -c "
SELECT
  pg_size_pretty(pg_database_size('fasten')) as db_size,
  pg_size_pretty(pg_total_relation_size('patient')) as patient_table_size;
"

Backup Strategy

1. Database Backups

Regular PostgreSQL backups are critical:

# Daily automated backup script
#!/bin/bash
BACKUP_DIR="/backups/fasten-health"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/fasten_backup_$DATE.sql.gz"

# Create backup
pg_dump -h example-postgres.klutch.sh -p 8000 -U fasten -d fasten | gzip > $BACKUP_FILE

# Verify backup
if [ $? -eq 0 ]; then
    echo "Backup successful: $BACKUP_FILE"

    # Remove backups older than 30 days
    find $BACKUP_DIR -name "fasten_backup_*.sql.gz" -mtime +30 -delete
else
    echo "Backup failed!"
    exit 1
fi

2. Volume Backups

Backup cache and uploaded documents:

#!/bin/bash
# Backup Fasten Health volumes
BACKUP_DIR="/backups/fasten-volumes"
DATE=$(date +%Y%m%d_%H%M%S)

# Backup cache directory
tar -czf "$BACKUP_DIR/cache_$DATE.tar.gz" -C /opt/fasten cache

# Backup logs
tar -czf "$BACKUP_DIR/logs_$DATE.tar.gz" -C /opt/fasten logs

# Remove old volume backups (keep 7 days)
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

3. Restore Procedures

Document and test restore procedures:

# Restore database from backup
gunzip -c fasten_backup_20241220_120000.sql.gz | \
  psql -h example-postgres.klutch.sh -p 8000 -U fasten -d fasten

# Restore cache volume
tar -xzf cache_20241220_120000.tar.gz -C /opt/fasten

# Restart Fasten Health
docker restart fasten-health

4. Backup Testing

Test backups quarterly:

Create a test environment with the same configuration
Restore the latest database backup
Restore the latest volume backups
Verify data integrity and functionality
Document any issues discovered

Monitoring and Alerts

1. Health Checks

Monitor Fasten Health availability:

#!/bin/bash
# Health check script
FASTEN_URL="https://your-app-name.klutch.sh/api/health"

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $FASTEN_URL)

if [ $RESPONSE -eq 200 ]; then
    echo "Fasten Health is healthy"
else
    echo "Fasten Health health check failed: HTTP $RESPONSE"
    # Send alert (email, Slack, etc.)
fi

2. Log Monitoring

Monitor Fasten Health logs for errors:

# View recent logs
tail -f /opt/fasten/logs/fasten.log

# Search for errors
grep -i error /opt/fasten/logs/fasten.log

# Monitor sync failures
grep -i "sync failed" /opt/fasten/logs/fasten.log

3. Key Metrics to Monitor

Application availability (uptime)
API response times
Database connection pool usage
Disk space on cache and log volumes
Sync job success rates
Failed authentication attempts
Error rates in application logs

Scaling Considerations

While Fasten Health is designed for personal use, consider these factors as your medical record grows:

1. Database Scaling

Start with PostgreSQL on a single instance
Monitor query performance as data grows
Consider database connection pooling (PgBouncer) if needed
Index frequently queried fields

2. Storage Scaling

Monitor volume usage monthly
Increase cache volume size as you connect more providers
Implement log rotation to prevent log volume from filling up

3. Multiple Users (Family Accounts)

If managing health records for family members:

Each family member should have their own account
Consider increasing database and cache volume sizes
Monitor concurrent user sessions
Adjust PostgreSQL max_connections if needed

Troubleshooting

Common Issues and Solutions

1. Database Connection Failures

Symptom: Fasten Health fails to start with database connection errors

Solutions:

Verify the database connection string in FASTEN_DATABASE_LOCATION
Ensure PostgreSQL is running and accessible
Check firewall rules allowing connections on port 8000
Verify database credentials are correct

Test connection manually:

psql "postgres://fasten:password@example-postgres.klutch.sh:8000/fasten?sslmode=require"

2. Provider Sync Failures

Symptom: Medical records not syncing from healthcare providers

Solutions:

Check provider authorization status in the Sources page
Re-authorize the provider connection
Review sync logs: grep "sync" /opt/fasten/logs/fasten.log
Verify provider credentials haven’t expired
Check if provider API is experiencing downtime
Increase sync interval if hitting rate limits

3. JWT Authentication Errors

Symptom: Users unable to log in or getting “Invalid token” errors

Solutions:

Verify FASTEN_JWT_ISSUER_KEY is set and at least 32 characters
Ensure JWT key hasn’t changed (users must re-login after key rotation)
Check JWT expiration settings
Clear browser cookies and cache

4. Disk Space Issues

Symptom: Application errors related to disk space

Solutions:

Check volume usage:

df -h /opt/fasten/cache
df -h /opt/fasten/logs

Increase volume size in Klutch.sh dashboard

Implement log rotation:

find /opt/fasten/logs -name "*.log" -mtime +30 -delete

Review cache directory for orphaned files

5. Slow Performance

Symptom: Dashboard loading slowly or timeouts

Solutions:

Check database query performance
Review PostgreSQL slow query log

Optimize database indexes:

-- Create indexes on frequently queried fields
CREATE INDEX idx_patient_id ON observation(patient_id);
CREATE INDEX idx_effective_date ON observation(effective_date_time);

Monitor CPU and memory usage
Consider upgrading to a larger database instance

6. Failed Deployments

Symptom: Deployment fails on Klutch.sh

Solutions:

Review build logs in Klutch.sh dashboard
Verify Dockerfile syntax
Check that all base images are accessible
Ensure build dependencies are available
Verify environment variables are set correctly

Test Dockerfile locally before deploying:

docker build -t fasten-health .
docker run -p 8080:8080 fasten-health

7. Missing Medical Records

Symptom: Expected medical records not appearing in Fasten Health

Solutions:

Verify provider is FHIR-compatible
Check sync logs for errors
Ensure date ranges cover the expected records
Re-authorize provider connection
Verify provider account has access to the records
Check if provider requires additional consent forms

Debug Mode

Enable debug logging for troubleshooting:

# Set debug log level
FASTEN_LOG_LEVEL=DEBUG

# Restart Fasten Health
docker restart fasten-health

# Monitor detailed logs
tail -f /opt/fasten/logs/fasten.log | grep DEBUG

Getting Help

If you encounter issues not covered here:

Check the Fasten Health GitHub Issues
Join the Fasten Health Discord community
Review the official Fasten Health documentation
Contact Klutch.sh support for platform-specific issues

Additional Resources

Your Health, Your Data, Your Control - With Fasten Health on Klutch.sh, you have complete ownership of your medical records in a secure, private environment. Start consolidating your healthcare data today and take control of your health journey.