WIRACHEL AWS

Deploy RACHEL educational content platform with Kolibri, Kiwix, and KA-Lite on AWS Lightsail, plus a multi-facility prison portal system.

Overview

This project provides an automated installation script to deploy a complete offline educational content server on Ubuntu 22.04 (AWS Lightsail). It includes:

• RACHEL ContentShell - Web-based educational content management
• Kolibri - Learning platform by Learning Equality
• Kiwix - Offline Wikipedia and other ZIM content
• KA-Lite - Khan Academy offline platform
• Facility Portal - Multi-tenant portal with subdomain isolation for prison facilities

Requirements

• AWS Lightsail instance (recommended: $10/month plan, 2GB RAM)
• Ubuntu 22.04 LTS
• Minimum 50GB storage (350GB+ recommended for full content)
• Static IP recommended

Quick Start

1. Create Lightsail Instance

# Create instance via AWS CLI
aws lightsail create-instances \
    --instance-names wirachel-poc \
    --availability-zone us-east-1a \
    --blueprint-id ubuntu_22_04 \
    --bundle-id small_3_0 \
    --key-pair-name your-key-pair

# Allocate and attach static IP
aws lightsail allocate-static-ip --static-ip-name wirachel-ip
aws lightsail attach-static-ip --static-ip-name wirachel-ip --instance-name wirachel-poc

# Open required ports (HTTP, HTTPS, and service ports)
aws lightsail open-instance-public-ports \
    --instance-name wirachel-poc \
    --port-info fromPort=80,toPort=80,protocol=TCP
aws lightsail open-instance-public-ports \
    --instance-name wirachel-poc \
    --port-info fromPort=443,toPort=443,protocol=TCP
aws lightsail open-instance-public-ports \
    --instance-name wirachel-poc \
    --port-info fromPort=8080,toPort=8082,protocol=TCP
aws lightsail open-instance-public-ports \
    --instance-name wirachel-poc \
    --port-info fromPort=8443,toPort=8445,protocol=TCP

2. Run Installation Script

# SSH into your instance
ssh -i your-key.pem ubuntu@YOUR_STATIC_IP

# Download and run installer
git clone https://github.com/YOUR_USERNAME/wirachel-aws.git
cd wirachel-aws
chmod +x install.sh
sudo ./install.sh

Access URLs

After installation and SSL setup, access the services at:

Service	HTTP	HTTPS	Description
RACHEL	http://YOUR_DOMAIN/	https://YOUR_DOMAIN/	Main educational content portal
Kolibri	http://YOUR_DOMAIN:8080/	https://YOUR_DOMAIN:8443/	Learning Equality platform
Kiwix	http://YOUR_DOMAIN:8081/	https://YOUR_DOMAIN:8444/	Offline Wikipedia/ZIM content
KA-Lite	http://YOUR_DOMAIN:8082/	https://YOUR_DOMAIN:8445/	Khan Academy offline

Note: HTTPS on ports 8443-8445 uses nginx as an SSL termination proxy to the backend services.

Default Credentials

KA-Lite Admin

• Username: admin
• Password: Rachel2025

Kolibri

• Set up via web wizard on first visit
• Create your own admin account

RACHEL Admin

• Access admin panel at http://YOUR_IP/admin/
• Default: no authentication (configure as needed)

Service Management

# Check service status
sudo systemctl status nginx
sudo systemctl status kolibri
sudo systemctl status kalite
sudo systemctl status kiwix-serve

# Restart services
sudo systemctl restart nginx
sudo systemctl restart kolibri
sudo systemctl restart kalite
sudo systemctl restart kiwix-serve

# View logs
sudo journalctl -u kolibri -f
sudo journalctl -u kalite -f
sudo journalctl -u kiwix-serve -f

Adding Content

RACHEL Modules

# Copy content to modules directory
sudo rsync -av /path/to/modules/ /media/RACHEL/rachel/modules/
sudo chown -R www-data:www-data /media/RACHEL/rachel/modules/

Kiwix ZIM Files

# Download ZIM files (example: Wikipedia)
cd /var/kiwix/data
sudo wget https://download.kiwix.org/zim/wikipedia_en_all_maxi.zim

# Create library file and restart
sudo /var/kiwix/bin/kiwix-manage /var/kiwix/data/library.xml add *.zim
sudo systemctl restart kiwix-serve

Kolibri Content

1. Go to http://YOUR_IP:8080/
2. Complete setup wizard
3. Navigate to Device > Channels
4. Import content channels

KA-Lite Content

1. Go to http://YOUR_IP:8082/
2. Login as admin
3. Navigate to Manage > Videos
4. Download desired content

Architecture

┌────────────────────────────────────────────────────────────────────────────┐
│                              Ubuntu Server                                  │
├────────────────────────────────────────────────────────────────────────────┤
│                           Nginx (SSL Termination)                           │
├──────────────┬──────────────┬──────────────┬──────────────────────────────┤
│  Port 443    │  Port 8443   │  Port 8444   │       Port 8445              │
│  (HTTPS)     │  (HTTPS)     │  (HTTPS)     │       (HTTPS)                │
│   RACHEL     │   Kolibri    │    Kiwix     │       KA-Lite                │
│  PHP-FPM     │  proxy→8080  │  proxy→8081  │      proxy→8082              │
└──────────────┴──────────────┴──────────────┴──────────────────────────────┘

Note: Services run on internal HTTP ports (8080-8082) with nginx providing SSL termination on HTTPS ports (8443-8445). This preserves CSS/static assets.

Directory Structure

/media/RACHEL/rachel/       # RACHEL ContentShell
├── modules/                # Educational content modules
├── admin/                  # Admin interface
└── ...

/var/kolibri/               # Kolibri data
/var/kiwix/                 # Kiwix installation
├── bin/                    # Kiwix binaries
└── data/                   # ZIM files and library

/var/ka-lite/               # KA-Lite data
/opt/ka-lite/               # KA-Lite installation
└── venv27/                 # Python 2.7 virtualenv

Estimated Costs (AWS Lightsail)

Plan	Monthly Cost	RAM	Storage	Best For
$10	~$15-16 (with disk)	2GB	50GB	POC/Testing
$20	~$44 (with 240GB disk)	4GB	300GB	Small deployment
$40	~$80	8GB	500GB+	Full production

Troubleshooting

KA-Lite won't start

# Check Python 2.7 is installed
python2.7 --version

# Check service logs
sudo journalctl -u kalite -n 50

# Manual start for debugging
sudo -u www-data KALITE_HOME=/var/ka-lite /opt/ka-lite/venv27/bin/kalite start --foreground

Kiwix shows inactive

Kiwix requires ZIM files to start. Add files to /var/kiwix/data/ first.

Kolibri not accessible

# Check if running on correct port
ss -tlnp | grep 8080

# Restart service
sudo systemctl restart kolibri

SSL/HTTPS Setup

To enable HTTPS with Let's Encrypt:

# Install certbot
sudo apt-get install -y certbot python3-certbot-nginx

# Get certificate (replace YOUR_DOMAIN)
sudo certbot --nginx -d YOUR_DOMAIN -d www.YOUR_DOMAIN --non-interactive --agree-tos --email admin@YOUR_DOMAIN --redirect

The install script creates nginx configs for HTTPS on service ports (8443-8445). Open these ports in Lightsail after SSL setup:

aws lightsail open-instance-public-ports \
    --instance-name wirachel-poc \
    --port-info fromPort=8443,toPort=8445,protocol=TCP

Security Notes

⚠️ Important: Change default passwords before production use!

# Change KA-Lite admin password
sudo -u www-data KALITE_HOME=/var/ka-lite /opt/ka-lite/venv27/bin/kalite manage changepassword admin

For production:

• Configure firewall rules
• Set up regular backups
• Change all default credentials

License

MIT License - See LICENSE for details.

Facility Portal System

The facility portal provides subdomain-based isolation for multiple prison facilities, enabling:

• Print Request Forms - Inmates can submit print requests
• Custom Form Builder - Admins create facility-specific forms
• Submission Export - Export data as JSON/CSV
• Content Module Control - Enable/disable RACHEL/Kolibri/Kiwix modules per facility
• User Management - Facility-scoped user administration

Portal Architecture

*.wirachel.org → nginx (wildcard routing) → Node.js portal (port 3000)
                                              ↓
                                         PostgreSQL (multi-tenant with RLS)
                                              ↓
                                         S3 (file uploads)

Portal URLs

Subdomain	Purpose
demo.wirachel.org	Demo facility portal
{facility}.wirachel.org	Facility-specific portals

Demo Credentials

• Email: admin@demo.wirachel.org
• Password: admin123

Creating New Facilities

# SSH into server
ssh -i ~/.ssh/lightsail-wirachel.pem ubuntu@54.152.32.243

# Connect to PostgreSQL
sudo -u postgres psql wirachel_portal

# Create new facility
INSERT INTO facilities (slug, name) VALUES ('facility-name', 'Facility Display Name');

# Create admin user for facility (replace password hash)
INSERT INTO users (facility_id, email, password_hash, name, role)
SELECT id, 'admin@facility-name.wirachel.org', 
       '$2a$10$...hash...', 'Admin Name', 'admin'
FROM facilities WHERE slug = 'facility-name';

Portal Management

# Service management
sudo systemctl status wirachel-portal
sudo systemctl restart wirachel-portal
sudo journalctl -u wirachel-portal -f

# Run migrations
cd /var/www/portal && npm run migrate

AWS Infrastructure

• Route 53 Hosted Zone: Z05917061EBGOZDDGMVZ1
• S3 Bucket: wirachel-uploads (private, encrypted)
• Wildcard DNS: *.wirachel.org → 54.152.32.243

Pending Setup

After DNS propagates from Squarespace to Route 53 nameservers:

# Generate wildcard SSL certificate
sudo certbot certonly --dns-route53 -d wirachel.org -d '*.wirachel.org' \
    --non-interactive --agree-tos -m admin@wirachel.org

Route 53 Nameservers (update in Squarespace):

• ns-687.awsdns-21.net
• ns-1173.awsdns-18.org
• ns-2021.awsdns-60.co.uk
• ns-206.awsdns-25.com

License

MIT License - See LICENSE for details.

Contributing

Pull requests welcome! Please open an issue first for major changes.

Acknowledgments

• World Possible / RACHEL
• Learning Equality / Kolibri
• Kiwix
• KA-Lite