Skip to main content

Self-Host using Docker

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.

Check if you already have the prerequisites installed by running the below commands in your terminal

Node: node -v
Yarn: yarn -v
Docker: docker -v

System Requirements​

  • Linux VM (Ubuntu 20.04+ recommended)
  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Node.js 18+
  • Yarn 1.22+
  • Nginx
  • Minimum 4GB RAM
  • At least 20GB free disk space
  • Internet connectivity
  • Custom domain names with DNS configured

Installation​

1. Clone the Sparrow App repository:​

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

cd sparrow-app

2. Configure .env.docker-setup​

You can move ahead with the default values or customize the environment variables in .env.docker-setup according to the Environment Variable Guide.

This file contains the environment configurations for all Sparrow services (Web, API, Auth, Admin, Proxy, MongoDB).

3. Set Up Custom Domains​

To map your custom domain to the services running on your Docker setup, create A records for each service pointing to your server’s public IP address.

Example DNS record:

TypeName (Host)Value (Points to)TTL
AbackendYOUR_PUBLIC_IP3600 or Auto
AauthYOUR_PUBLIC_IP3600 or Auto
AappYOUR_PUBLIC_IP3600 or Auto
AsocketYOUR_PUBLIC_IP3600 or Auto
AproxyYOUR_PUBLIC_IP3600 or Auto
AadminYOUR_PUBLIC_IP3600 or Auto

Replace YOUR_PUBLIC_IP with the public IP address of your server running Docker.

Each of these subdomains (e.g., backend.yourdomain.com, auth.yourdomain.com, etc.) will allow external access to the corresponding services running inside Docker containers.

4. Run the Setup Script​

info

This script helps you map Sparrow services to your own custom domain and secure them with SSL.

Navigate to the directory where the setup_nginx_proxy_ssl.sh script is located and run the following command:

cd /home
./setup_nginx_proxy_ssl.sh

Once executed, you’ll see a welcome message and a list of services:

========================================
Welcome to Sparrow 
========================================
Let's begin with your domain setup.
Choose what you need to setup from the options below:
Note: Services marked with ✔ already have domain, SSL and NGINX configured.
[1] Backend [PORT: 9000]
[2] Socket [PORT: 9001] ✔ (sparrowsocket.test.com)
[3] App [PORT: 1422] ✔ (sparrowapp.test.com)
[4] Auth [PORT: 1421]
[5] Proxy [PORT: 3000]
[6] Admin [PORT: 5173] 
[7] Exit

Select the Service to Configure

When prompted, enter the number for the service you want to configure
(e.g., enter 1 for the Backend).

info

Services already configured will show a ✔️ and the linked domain name.

5. Start All Sparrow Services​

Once the environment file (.env.docker-setup) is configured and your custom domains are mapped, start all the services with Docker Compose by running the following command:

 yarn docker:up

Upon successful execution of the above command, the following services will be started inside different docker containers:

  • Sparrow Web Server
  • Sparrow API Server
  • Sparrow Auth Server
  • Sparrow Proxy Server
  • Sparrow Admin Server
  • MongoDB

6. Access the Sparrow App​

Open a web browser and go to your custom domain (e.g., sparrowapp.test.com) to access the Sparrow App.

Stopping the Services​

In order to stop all the services, run the below command:

yarn docker:down
info

This will stop all Sparrow containers while keeping your configuration and data safe. You can restart them anytime with yarn docker:up.