Skip to main content

Installation

Docker is the easiest way to get started with self-hosted Sparrow. This guide assumes you are running the command from the machine you intend to host from.

Before you begin

info

You need the following installed in your system: Git and Docker.

First clone the SparrowAPI repository:

git clone https://github.com/sparrowapp-dev/sparrow-api.git
cd sparrowapp-dev

Create env

cp .env.example .env

ENV Configuration

# APP
PORT=9000
APP_ENV= DEV
APP_URL= http://localhost

# AUTH
JWT_SECRET_KEY= Provide the secret key for JWT (JSON Web Tokens) encryption
JWT_EXPIRATION_TIME= Set the expiration time for JWT tokens in seconds.

# DATABASE
DB_URL= Input the URL of your database.

# Google OAuth
GOOGLE_CLIENT_ID= Specify the Google Client ID.
GOOGLE_CLIENT_SECRET= Provide the Google Client Secret.
GOOGLE_APP_URL= Set the URL of the Google application.
LOGIN_REDIRECT_URL=Define the URL to redirect after successful login.
GOOGLE_ACCESS_TYPE=Specify the access type for Google OAuth.

# EXPIRY TIME FOR EMAIL VALIDATION CODE/LINK
EMAIL_VALIDATION_CODE_EXPIRY_TIME=Set the expiry time for email validation codes/links.

# KAFKA
KAFKA_BROKER=Input the Kafka broker details.
 
#EMAIL
SMTP_SENDER_EMAIL= Provide the sender's email address for SMTP.
SMTP_SENDER_PASSWORD= Input the sender's password for SMTP authentication.
SMTP_MAIL_HOST= Set the SMTP mail host.
SMTP_MAIL_PORT= Specify the SMTP mail port.
SMTP_MAIL_SECURE= Define the SMTP mail security method
SMTP_USER_NAME= Provide the SMTP username.
 
# REFRESH TOKEN
REFRESH_TOKEN_SECRET_KEY=refresh-token-secret
REFRESH_TOKEN_EXPIRATION_TIME=604800
REFRESH_TOKEN_MAX_LIMIT=50
 
 # APP UPDATER
 APP_UPDATE_AVAILABLE=true
 APP_VERSION=
 WINDOWS_APP_SIGNATURE= 
 WINDOWS_APP_URL= 
 MAC_APPLE_SILICON_APP_SIGNATURE=
 MAC_APPLE_SILICON_APP_URL=
 MAC_INTEL_APP_SIGNATURE=
 MAC_INTEL_APP_URL=

# SUPPORT
 SPARROW_EMAIL=contactus@sparrowapp.dev

Now, you can use docker-compose to start Sparrow API.

# Pull the latest images
docker compose pull

# Start the services (in detached mode)
docker compose up -d

After all the services have started you can see them running in the background

docker compose ps

Accessing Sparrow API swagger

http://localhost/api/docs

Production Environments Docker Setup​

Custom Domian using NGNIX reverse proxy and SSL with Let's Encrypt.

Need to create below file structure in existing repository.

sparrowapp-dev/
│
├── docker-compose.yml
├── nginx/
│   ├── Dockerfile
│   ├── nginx.conf
│   └── certbot/
│       └── Dockerfile
└── volumes/
    └── nginx/

Production docker-compose.yml with Ngnix and SSL

version: "3.8"

services:
  # Sparrow API
  sparrow:
    build:
      dockerfile: Dockerfile
    ports:
      - "9000:9000"
    env_file:
      - .env
    networks:
      - localnet

  # MongoDB
  mongo:
    image: mongo:7.0
    environment:
      MONGO_INITDB_ROOT_USERNAME: YOUR_USERNAME
      MONGO_INITDB_ROOT_PASSWORD: YOUR_PASSWORD
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db
    networks:
      - localnet

  # Kafka
  kafka:
    image: bitnami/kafka:3.4.1
    hostname: kafka
    ports:
      - "9092:9092"
    volumes:
      - "kafka_data:/bitnami"
    environment:
      - KAFKA_ENABLE_KRAFT=yes
      - KAFKA_CFG_PROCESS_ROLES=broker,controller
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093,EXTERNAL://:9094
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,EXTERNAL:PLAINTEXT
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092,EXTERNAL://kafka:9094
      - KAFKA_BROKER_ID=1
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@localhost:9093
      - ALLOW_PLAINTEXT_LISTENER=yes
      - KAFKA_CFG_NODE_ID=1
      - KAFKA_AUTO_CREATE_TOPICS_ENABLE=true
      - KAFKA_CFG_NUM_PARTITIONS=2
      - KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1
      - KAFKA_TRANSACTION_STATE_LOG_MIN_ISR=1
      - KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=1
      - KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS=0
      - KAFKA_MESSAGE_MAX_BYTES=1000000
    deploy:
      resources:
        limits:
          cpus: "1"
          memory: 1G

  # NGINX Reverse Proxy
  nginx:
    build:
      context: ./nginx
      dockerfile: Dockerfile
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./volumes/nginx:/etc/nginx
    networks:
      - localnet


volumes:
  mongo_data:   
  kafka_data:
    driver: local

networks:
  localnet:
    attachable: true

NGINX Configuration NGINX Dockerfile (nginx/Dockerfile)

FROM nginx:latest
RUN rm /etc/nginx/conf.d/default.conf
COPY nginx.conf /etc/nginx/conf.d

NGINX Configuration File (nginx/nginx.conf)

server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://sparrow:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location ~ /.well-known/acme-challenge {
        allow all;
        root /var/www/certbot;
    }
}

server {
    listen 443 ssl;
    server_name your_domain.com;

    ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem;

    location / {
        proxy_pass http://sparrow:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Certbot Dockerfile (nginx/certbot/Dockerfile)

FROM certbot/certbot

Run docker-compose up -d to start all services.

info

Ensure you have a valid domain name and update your_domain.com with your actual domain in NGINX configuration files.