Welcome to the MOSIP Infrastructure documentation! This index helps you find exactly what you need, whether you're a complete beginner or an experienced DevOps engineer.
Start your MOSIP deployment journey here:
- Glossary - Learn all the technical terms
- What is AWS? What is Kubernetes? What is Terraform?
- Plain language explanations for every concept
- No prior cloud knowledge required
- Secret Generation Guide - Create required credentials
- Step-by-step SSH key generation
- How to get AWS credentials
- Creating passwords and VPN configs
- Includes links to official documentation
- Workflow Guide - Run deployments through GitHub
- Visual walkthrough of GitHub Actions interface
- Where to click and what to select
- Understanding dry-run vs actual deployment
- Screenshots and examples
- DSF Configuration Guide - Configure MOSIP services
- What is a DSF file and why you need it
- How to find and update clusterid
- Domain configuration explained
- Examples for each setting
- Environment Destruction Guide - Clean up resources
- Safe teardown procedures
- How to avoid unexpected costs
- Backup before destruction
- Complete cleanup verification
Jump directly to what you need:
- Terraform Infrastructure: See terraform/README.md
- Helmsman Deployment: See Helmsman/README.md
- WireGuard VPN Setup: See terraform/base-infra/WIREGUARD_SETUP.md
- GitHub Actions Workflows: See [.github/workflows/]../.github/workflows/)
| Document | Description | Who Should Read |
|---|---|---|
| Main README | Complete deployment overview and quick start guide | Everyone - start here |
| Glossary | Technical terms explained in plain language | Beginners |
| Secret Generation Guide | How to create all required secrets and credentials | Everyone before deployment |
| Workflow Guide | Visual GitHub Actions workflow navigation | Everyone during deployment |
| DSF Configuration Guide | Helmsman configuration file explained in detail | Everyone before Helmsman deployment |
| Environment Destruction Guide | Safe resource cleanup and cost management | Everyone when decommissioning |
| Helmsman Destroy Guide | How to safely undeploy MOSIP services from Kubernetes | Everyone when removing services |
| Component | Document | What It Covers |
|---|---|---|
| Terraform | terraform/README.md | Infrastructure as code, tfvars, modules, state management |
| Helmsman | Helmsman/README.md | Application deployment, DSF files, hooks, troubleshooting |
| Helmsman Destroy | HELMSMAN_DESTROY_GUIDE.md | Undeploying services, data backup, cleanup procedures |
| WireGuard | terraform/base-infra/WIREGUARD_SETUP.md | VPN setup, peer configuration, client installation |
| Workflows | Helmsman/helmsman-workflow-guide.md | Helmsman workflow details |
Time required: 2-3 days for first deployment
- Day 1: Learning & Setup
- Read Glossary - Understand all terms (2 hours)
- Read Main README - Get deployment overview (1 hour)
- Follow Secret Generation Guide - Create all secrets (2 hours)
- Set up AWS account and configure IAM permissions
- Day 2: Infrastructure Deployment
- Follow Workflow Guide - Deploy base-infra (1 hour)
- Follow WireGuard Setup - Configure VPN (1 hour)
- Deploy main infrastructure (1 hour)
- Verify all components working
- Day 3: Application Deployment
- Follow DSF Configuration Guide - Update configs (2 hours)
- Deploy prerequisites and external services (1 hour)
- Deploy MOSIP core services (2 hours)
- Verify deployment and test access
Time required: 4-6 hours for first deployment
- Planning (30 minutes)
- Skim Main README - Understand MOSIP architecture
- Review Glossary - MOSIP-specific terms only
- Check Secret Generation Guide - What secrets are needed
- Infrastructure (2 hours)
- Configure terraform.tfvars files
- Run Terraform workflows
- Set up WireGuard VPN
- Applications (2-3 hours)
- Update DSF files using DSF Configuration Guide
- Run Helmsman workflows
- Verify deployment
Quick reference for common tasks:
- New deployment: Follow Quick Start in Main README
- Updating configurations: DSF Configuration Guide
- Troubleshooting: Check component-specific READMEs
- Cleanup: Environment Destruction Guide
| I Want To... | Read This |
|---|---|
| Understand what "Kubernetes" means | Glossary |
| Generate SSH keys | Secret Generation Guide - SSH Keys |
| Get AWS credentials | Secret Generation Guide - AWS Credentials |
| Run my first workflow | Workflow Guide - Base Infrastructure |
| Understand dry-run vs apply | Workflow Guide - Parameters |
| Fix "clusterid not found" error | DSF Configuration Guide - clusterid |
| Configure PostgreSQL | DSF Configuration Guide - PostgreSQL |
| Add reCAPTCHA keys | DSF Configuration Guide - reCAPTCHA |
| Delete my environment | Environment Destruction Guide |
| Check costs after deletion | Environment Destruction Guide - Cost Monitoring |
| Understand workflow names | Workflow Guide - Understanding Workflow Names |
| Technology | Learn About It | Use It |
|---|---|---|
| AWS | Glossary - AWS | Main README - AWS Setup |
| Terraform | Glossary - Terraform | Terraform README |
| Kubernetes | Glossary - Kubernetes | All deployment guides |
| Helmsman | Glossary - Helmsman | DSF Configuration Guide |
| WireGuard | Glossary - WireGuard | WireGuard Setup Guide |
| GitHub Actions | Glossary - GitHub Actions | Workflow Guide |
| Error | Solution |
|---|---|
| "clusterid not found" | DSF Configuration Guide - clusterid |
| "Authentication failed" | Secret Generation Guide - AWS Credentials |
| "InsufficientInstanceCapacity" | Main README - AWS Capacity Issues |
| "Namespace stuck in Terminating" | Environment Destruction Guide - Troubleshooting |
| "Can't find workflow" | Workflow Guide - Issue 1 |
| "Helmsman dry-run fails" | Workflow Guide - Issue 5 |
✅ Plain Language
- Every technical term explained
- No assumptions about prior knowledge
- Real-world analogies and examples
✅ Step-by-Step Instructions
- Numbered steps you can follow exactly
- "What you should see" at each step
- Clear success/failure indicators
✅ Visual Guidance
- Where to click in GitHub interface
- What buttons to press
- Expected output examples
✅ Comprehensive Examples
- Real configuration examples
- Before/after comparisons
- Common patterns explained
✅ Links to Official Docs
- Every tool linked to official documentation
- Additional learning resources
- Community support channels
✅ Troubleshooting Sections
- Common errors and solutions
- "What went wrong" explanations
- Recovery procedures
- Check the relevant guide - Use the tables above to find what you need
- Search for error messages - Use Ctrl+F in documentation
- Review troubleshooting sections - Each guide has a troubleshooting section
- Check official documentation - Follow links to tool-specific docs
- Ask the community - Open a GitHub issue with details
- What you're trying to do: "Deploy base infrastructure"
- What guide you're following: "Step 3a in Main README"
- What happened: Error message or unexpected behavior
- What you expected: What you thought would happen
- What you've tried: Steps you took to fix it
| Symbol | Meaning |
|---|---|
| Important for beginners | |
| Helpful tip or explanation | |
| Warning - pay attention! | |
| ✅ | Recommended action |
| ❌ | Action to avoid |
| Link to external documentation | |
| Link to our documentation | |
| Step-by-step guide available | |
| Security-related | |
| Deletion/cleanup related |
- Bold: Important terms, action items
Code: Commands, file names, values to copy-
Blockquotes: Important notes, warnings
code blocks: Multi-line commands, configuration examples
Found something unclear? Want to add more examples? Contributions welcome!
- Report issues: Open a GitHub issue describing what's confusing
- Suggest improvements: What would make docs clearer?
- Share your experience: What worked? What didn't?
# Check Kubernetes cluster
kubectl get nodes
kubectl get namespaces
kubectl get pods --all-namespaces
# Check specific services
kubectl get pods -A
kubectl get pods -n postgres
kubectl get svc -n istio-system
# View logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --follow
# Describe resources
kubectl describe pod <pod-name> -n <namespace>
kubectl describe svc <service-name> -n <namespace>- Read Glossary if new to cloud
- Generate all secrets (Guide)
- Configure terraform.tfvars files
- Deploy base infrastructure (Workflow Guide)
- Set up WireGuard VPN (Setup Guide)
- Deploy main infrastructure (Workflow Guide)
- Update DSF files (DSF Guide)
- Deploy prerequisites & external services
- Deploy MOSIP core services
- Deploy test rigs (optional)
- Verify deployment
- Document your deployment
Need to go back? Return to Main README
Have questions? Open an issue on GitHub!