Shortas Documentation

Deployment Guide

This guide covers deployment strategies, configuration, and operational considerations for Shortas in various environments.

🚀 Deployment Options

💻

Local Development

Development environment setup with all necessary tools and dependencies.

Learn More
🐳

Docker Deployment

Containerized deployment with Docker and Docker Compose.

Learn More
☸️

Kubernetes

Container orchestration for production-scale deployments.

Learn More
☁️

AWS Production

Cloud deployment with AWS services and infrastructure.

Learn More

📋 Prerequisites

System Requirements

🚀 Quick Start Deployment

For a rapid local deployment, use the make commands from the project root:

# Complete development setup (installs deps, starts infra, builds, tests)
make dev-setup

# Start all services in development mode
make dev-start

# Check if all services are healthy
make health-check

🐳 Docker Deployment

Docker is the recommended way to run Shortas in development and staging environments.

Building Docker Images

From the project root, build all service images:

make build-docker

This will create images for click-router, click-tracker, click-aggregator, click-router-api, and click-aggregator-api.

Deploying with Docker Compose

The docker-compose.yml file in the redirect/ directory orchestrates all Shortas services and their dependencies (MongoDB, ClickHouse, Redis, Kafka/Fluvio).

  1. Navigate to the redirect directory: 
    cd redirect
  2. Start the services: 
    docker-compose up -d

    This command will pull necessary images, create containers, and start all services in detached mode.

  3. Verify services: 
    docker-compose ps
# Or use the project's health check
cd .. # Go back to root
make health-check
  4. Stop services: 
    cd redirect
docker-compose down

☸️ Kubernetes Deployment

For production environments, Kubernetes provides robust orchestration, scaling, and self-healing capabilities. Example manifests are provided in infra/aws/terraform.

Prerequisites

Deployment Steps

  1. Create Namespace: 
    kubectl apply -f infra/aws/terraform/namespace.yaml
  2. Create ConfigMaps: Define application configurations as ConfigMaps. 
    kubectl apply -f infra/aws/terraform/click-router-configmap.yaml
# Repeat for other services (click-tracker, click-aggregator, etc.)

  3. Deploy Databases: Deploy MongoDB, ClickHouse, and Redis using their respective Kubernetes manifests or Helm charts. Ensure persistent storage is configured.

  4. Deploy Message Queues: Deploy Kafka/Fluvio using their Kubernetes manifests or Helm charts.

  5. Deploy Shortas Services: Apply the deployment manifests for each Shortas microservice. 
    kubectl apply -f infra/aws/terraform/click-router-deployment.yaml
kubectl apply -f infra/aws/terraform/click-router-service.yaml
kubectl apply -f infra/aws/terraform/click-router-ingress.yaml
# Repeat for other services
  6. Monitor Deployment: 
    kubectl get pods -n shortas
kubectl get services -n shortas
kubectl get ingress -n shortas

☁️ AWS Production Deployment

Shortas can be deployed on AWS using Terraform for infrastructure as code. The infra/aws/terraform directory contains example Terraform configurations.

Prerequisites

Deployment Steps

  1. Initialize Terraform: 
    cd infra/aws/terraform
terraform init
  2. Review and Plan: 
    terraform plan
  3. Apply Terraform: 
    terraform apply

    This will provision AWS resources including:

    • EKS Cluster (Kubernetes)
    • EC2 instances for services
    • RDS for MongoDB (or DynamoDB tables)
    • MSK for Kafka (or Fluvio on EC2)
    • ElastiCache for Redis
    • Load Balancers, Security Groups, etc.

⚙️ Configuration Management

Refer to the Configuration Guide for detailed information on environment variables and TOML configuration files.

🗄️ Database Setup

Ensure your databases are properly set up and accessible by Shortas services.

MongoDB

ClickHouse

Redis

📊 Analytics Setup

Configure your message queues for click stream processing.

Kafka

Fluvio

🔒 Security Configuration

Implement robust security measures for your deployments.

TLS/SSL

Firewall Configuration

Authentication & Authorization

📈 Monitoring & Logging

Set up comprehensive monitoring and logging for observability.

Health Checks

Logging

🚀 Performance Optimization

Tune your environment and application for maximum performance.

System Tuning

Application Tuning

🔄 Backup & Recovery

Implement backup strategies for critical data.

Database Backup

Application Backup

🚨 Troubleshooting

Common issues and debugging tips.

Need help with deployment? Check the Issue Tracker or our Support section.