Skip to content

installation.md

Latest commit

 

History

History
174 lines (115 loc) · 3.6 KB

installation.md

File metadata and controls

174 lines (115 loc) · 3.6 KB

Installation Guide

This guide will help you install Obiente Cloud on your infrastructure. Choose the installation method that best fits your needs.

Prerequisites

Before installing, ensure you have:

  • Docker 24.0 or higher installed
  • Docker Compose 2.0 or higher (for local development)
  • Linux OS (Ubuntu 22.04+ recommended)
  • Minimum 4GB RAM (8GB+ recommended)
  • 20GB+ free disk space
  • Network access for pulling Docker images

Verify Docker Installation

docker --version
docker compose version  # Or docker compose --version

Installation Methods

Choose the method that best suits your needs:

  1. Docker Compose - Simple, single-server deployment
  2. Docker Swarm - Simple - Distributed deployment with basic HA
  3. Docker Swarm - HA - Full high availability setup

Quick Install (Docker Compose)

For local development or testing:

# Clone the repository
git clone https://github.com/obiente/cloud.git
cd cloud

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
nano .env

# Start services
docker compose up -d

# Verify installation
docker compose ps

Production Install (Docker Swarm)

For production environments:

# Initialize Docker Swarm
docker swarm init

# Deploy the stack
docker stack deploy -c docker-compose.swarm.yml obiente

# Check status
docker service ls
docker stack services obiente

See Production Deployment for detailed instructions.

Verify Installation

After installation, verify everything is working:

1. Check Services

# Docker Compose (databases/services)
docker compose ps

# Docker Swarm (if using Swarm deployment)
docker service ls

2. Check Logs

# If running API locally: view the terminal output running `go run`

# Docker Swarm (API in Swarm)
docker service logs obiente_api

3. Test API

# Health check (includes metrics system status)
curl http://localhost:3001/health

# Should return: {"status":"healthy","version":"1.0.0","metrics_healthy":true}

# Check metrics observability
curl http://localhost:3001/metrics/observability

4. Test Database Connection

# Test PostgreSQL (main database)
docker exec -it obiente-postgres psql -U obiente-postgres -d obiente -c "\dt"

# Test TimescaleDB (metrics database)
docker exec -it obiente-timescaledb psql -U postgres -d obiente_metrics -c "\dt"

Next Steps

After successful installation:

  1. Configure Authentication - Set up Zitadel
  2. Configure Domains - Set up custom domains
  3. Set up Monitoring - Configure Prometheus and Grafana See the Troubleshooting guide

Common Issues

Docker Compose Not Found

# Ubuntu/Debian
sudo apt-get install docker-compose-plugin

# Or install via Docker Desktop

Permission Denied

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Port Already in Use

Edit docker-compose.yml or docker-compose.swarm.yml and change the port mappings.

Uninstall

Docker Compose

docker compose down -v

Docker Swarm

docker stack rm obiente

This removes all services and data volumes. Warning: This will delete all data!

Support

Having trouble? Check out:

Next: Configuration