NektoKZ — Anonymous Chat & Matchmaking Platform

NektoKZ is a high-performance, production-grade microservices platform for real-time anonymous text and voice communication. Built with Go (backend), Next.js (frontend), deployed on Oracle Cloud Infrastructure via Terraform.

---

Architecture Overview

The system follows a microservices architecture with all services communicating over an isolated Docker network (nektokz-network). Only the API Gateway is exposed to the public internet via Nginx Proxy Manager.

┌─────────────────────────────────────────────────────┐
│                    Internet                         │
└──────────────────────┬──────────────────────────────┘
                       │
              ┌────────▼────────┐
              │  Nginx Proxy    │
              │   Manager       │
              └────────┬────────┘
                       │
              ┌────────▼────────┐
              │   API Gateway   │  :8080
              └────────┬────────┘
                       │  nektokz-network
        ┌──────────────┼──────────────────┐
        │              │                  │
┌───────▼──────┐ ┌─────▼──────┐ ┌────────▼────────┐
│ user-service │ │chat-service│ │matchmaking-svc  │
│    :8081     │ │   :8083    │ │     :8082       │
└──────────────┘ └────────────┘ └─────────────────┘
        │              │
┌───────▼──────────────▼───────┐
│   nektokz-postgres  :5432    │
│   nektokz-redis     :6379    │
└──────────────────────────────┘

Services

Service	Port	Description
api-gateway	8080	Central entry point, request routing
user-service	8081	Authentication & profile management
matchmaking-service	8082	User matching algorithms
chat-service	8083	Real-time WebSocket messaging
moderation-service	8084	Content filtering & reporting
notification-service	8085	Internal event notifications

Infrastructure

Component	Technology
Backend	Go 1.25 / Chi v5
Frontend	Next.js 15
Database	PostgreSQL 16 / Redis 7
WebRTC	Coturn (STUN/TURN)
Monitoring	Prometheus / Grafana / Node Exporter
IaC	Terraform (Oracle Cloud / OCI)
Reverse Proxy	Nginx Proxy Manager

---

Prerequisites

• Docker & Docker Compose v2+ — required
• Go 1.25+ — only if running services locally without Docker
• Node.js 20+ & npm — only if running frontend locally
• Make — optional, used as a shortcut for Docker Compose commands

---

Local Setup

1. Clone & Configure Environment

git clone https://github.com/mathalama/anon.git
cd anon
cp .env.example .env
# Edit .env with your values

2. Start Infrastructure (PostgreSQL, Redis, Coturn)

With Make:

make up-infra

Without Make (Docker Compose directly):

docker compose -f docker-compose.infra.yml up -d

3. Run Database Migrations

With Make:

make migrate

Without Make:

docker compose -f docker-compose.infra.yml run --rm migrate

4. Start All Microservices

With Make:

make up-services

Without Make:

docker compose -f docker-compose.services.yml up -d

5. Start Monitoring Stack (Optional)

docker compose -f docker-compose.monitoring.yml up -d

6. Start Frontend

cd frontend
npm install
npm run dev

---

Makefile Commands

Command	Docker Compose Equivalent	Description
make up	docker compose -f docker-compose.infra.yml -f docker-compose.services.yml up -d	Start all backend containers
make up-infra	docker compose -f docker-compose.infra.yml up -d	Start PostgreSQL, Redis, Coturn
make up-services	docker compose -f docker-compose.services.yml up -d	Start all microservices
make down	docker compose -f docker-compose.infra.yml -f docker-compose.services.yml down	Stop and remove all containers
make migrate	docker compose -f docker-compose.infra.yml run --rm migrate	Run database migrations
make logs-services	docker compose -f docker-compose.services.yml logs -f	Tail logs for Go services
make logs-infra	docker compose -f docker-compose.infra.yml logs -f	View logs for DBs & Redis

---

Project Structure

├── api-gateway/              # Central entry point & routing
├── user-service/             # Authentication & profile management
├── chat-service/             # Real-time WebSocket messaging
├── matchmaking-service/      # User matching algorithms
├── moderation-service/       # Content filtering & reporting
├── notification-service/     # Internal event notifications
├── frontend/                 # Next.js web application
├── docker/
│   └── postgres/init/        # DB initialization scripts
├── terraform/                # OCI Infrastructure as Code
│   ├── main.tf
│   ├── variables.tf
│   ├── setup.sh
│   ├── outputs.tf
│   └── terraform.tfvars
├── monitoring/
│   └── prometheus/           # Prometheus config & scrape targets
├── docker-compose.infra.yml  # PostgreSQL, Redis, Coturn
├── docker-compose.services.yml # All microservices
├── docker-compose.monitoring.yml # Prometheus, Grafana, Node Exporter
├── Makefile
└── .env.example

---

Service Endpoints (Local)

Service	URL
Frontend	http://localhost:3000
API Gateway	http://localhost:8080
Nginx Proxy Manager Admin	http://localhost:81

---

Monitoring & Observability

The monitoring stack uses Prometheus for metrics collection and Grafana for visualization.

Prometheus scrapes metrics from all 6 microservices and the API Gateway via /metrics endpoints on their respective ports.

Grafana dashboards include:

• Service availability (up/down status per service)
• Node Exporter: CPU, RAM, Disk, Network for the host machine

To verify all services are UP:

1. Open Prometheus through an SSH tunnel or internal access path
2. All nektokz-services targets should show state UP

---

Infrastructure as Code (Terraform)

The server is provisioned on Oracle Cloud Infrastructure (OCI) using Terraform. See terraform/ for full configuration.

Provisioned Resources

• Compute Instance: VM.Standard.E2.1.Micro (Always Free tier)
• OS: Ubuntu 24.04 LTS
• Region: EU Stockholm (eu-stockholm-1)

Open Ports (Security Rules)

Port	Protocol	Purpose
22	TCP	SSH management
80	TCP	HTTP / API Gateway
443	TCP	HTTPS
81	TCP	Nginx Proxy Manager admin

Grafana and Prometheus should stay bound to 127.0.0.1 unless you intentionally place them behind VPN, SSH tunneling, or an allowlisted reverse proxy.

Deploy Infrastructure

cd terraform
cp terraform.tfvars.example terraform.tfvars
# Fill in your OCI credentials

terraform init
terraform plan
terraform apply

After apply, the public IP is printed as output: instance_public_ip.

---

Configuration & Deployment (Ansible)

Ansible is used to automate server configuration and application deployment.

1. Prerequisites

• Ansible installed on your local machine.
• SSH access to the provisioned server.

2. Configure Inventory

Update ansible/inventory.ini with your server's public IP:

[servers]
server1 ansible_host=YOUR_SERVER_IP ansible_user=ubuntu

3. Run Playbook

To configure the server (Docker, Swap, Git) and deploy the application:

cd ansible
ansible-playbook playbook.yml

Tags:

• setup: Run only server configuration tasks.
• deploy: Run only application deployment tasks.

Example (only deploy):

ansible-playbook playbook.yml --tags deploy

---

Refer to DEPLOYMENT.md for OCI cloud deployment details.

---

CI/CD

GitHub Actions workflows are located in .github/workflows/. The pipeline handles automated building and image publishing to ghcr.io/mathalama/.

---

License

This project is for educational and demonstration purposes. All rights reserved.