Setup & Installation

Sawtak is fully containerized and easy (easy enough - good luck with system resources though ~ Ahmed) to spin up locally for development and testing.

Prerequisites:

• Docker (with Compose plugin) or Podman (Recommended for easiest setup).
• Get Docker
• Get Podman
• Bun (Only required if you plan to run the services manually without Docker/Podman or if you want to run tests locally).

📦 Installing Bun

For Windows (PowerShell):

irm bun.sh/install.ps1|iex

For Linux/Mac:

curl -fsSL <https://bun.sh/install> | bash

💡 Note on Installation: You do not need to run bun install locally if you are using Docker/Podman Compose. The containers will handle installing all necessary dependencies internally.

Steps

1. Environment Variables: Create your .env file from the provided template.

   cp .env.example .env
   

   You must populate this file with your specific API keys, database URLs, and secrets (e.g., Gemini API key, Google Client ID, Proxy secrets).

2. Start the Stack: Use Docker Compose to spin up the entire suite of services.

   • Mac/Linux: Use the standard compose file.
   • Windows: Use the Windows-specific compose file (which handles Windows Docker networking differences).

   # For Mac/Linux (Docker)
   docker compose -f docker/docker-compose.prod-testnet.local.yml --env-file .env up -d
   
   # For Windows (Docker)
   docker compose -f docker/docker-compose.dev-windows-testnet.yml --env-file .env up -d
   

3. Start the Monitoring Stack (Optional): To spin up Prometheus and Grafana for system observability:

   docker compose -f monitoring/docker-compose.monitoring.yml --env-file .env up -d
   

4. Verify Health: Ensure the proxy is actively receiving traffic.

   curl <http://localhost:4000/health>
   

Using the Platform

Once your Docker containers are fully running, you can access the frontend web application by navigating to http://localhost:3000 in your browser.

Things to try out:

1. Public Feed: Visit the main feed to see the public stream of verified, anonymized complaints.
2. Login with Haweya: Try testing the secure National ID login flow using our mocked Haweya OAuth provider.
3. Submit Complaints: Go to the submission page and try creating both types of complaints:

• 🕵️ Anonymous Mode: Strip all identifying information; the payload is submitted completely anonymously, and evidence is uploaded publicly to IPFS.
• 🆔 Identified Mode: Submit a complaint using your identity, which is kept strictly confidential and encrypted via AES-256-GCM in our database, with evidence uploaded securely to private Cloudflare R2 storage.

4. Upload Evidence: Make sure to test uploading evidence directly from the complaint submission page for both modes.

Monitoring System Health

If you are an administrator, you can access the pre-configured Grafana dashboards at http://localhost:3100 (default login: admin/admin) to monitor network traffic, rate limits, server memory, and database connections.

Testing Locally

To run the automated tests locally, ensure you have bun installed on your machine. You can execute the test suite directly from the root directory:

bun test