annany/nebula-backend-server repository overview

⁠Nebula Backend Server

⁠Project Overview

Nebula (v0.2.0) is a Backend-as-a-Service (BaaS) MVP built with Go. It provides a set of APIs to manage databases, schemas, and records with basic authentication and authorization mechanisms. The project supports CORS, rate limiting, structured logging, and flexible authentication methods (JWT and API Keys).

This README outlines the steps to run Nebula in Docker containers, configure it using environment variables, and scale the backend service using Docker Compose.

⁠Prerequisites

Ensure you have the following installed:

• Docker (latest stable version)
• Docker Compose (latest stable version)

⁠Docker Setup

⁠1. Clone the Repository

Start by cloning the repository to your local machine.

git clone https://github.com/Annany2002/nebula-backend.git
cd nebula-backend

⁠2. Docker Compose Configuration

⁠Docker Compose File (docker-compose.yml)

The docker-compose.yml file is used to manage the multi-container setup for Nebula Backend. It defines two services:

• nebula-backend: The main backend service that handles API requests, with a scaled number of replicas (5 in this case).
• nginx: A reverse proxy for distributing external traffic to the backend service.

Here is a breakdown of the key configuration:

services:
  nebula-backend:
    image: nebula-backend
    environment:
      - SERVER_PORT=${SERVER_PORT}
      - JWT_SECRET=${JWT_SECRET}
      - JWT_EXPIRATION_HOURS=${JWT_EXPIRATION_HOURS}
      - DATABASE_DIRECTORY=${DATABASE_DIRECTORY}
      - DATABASE_DIRECTORY_FILE=${DATABASE_DIRECTORY_FILE}
    deploy:
      replicas: 5  # Scale backend service to 5 replicas
    ports:
      - "8080:8080"  # External port for the backend service
    networks:
      - backend_network

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf  # Custom Nginx config
    ports:
      - "80:80"  # Expose port 80 for external access
    networks:
      - backend_network

networks:
  backend_network:
    driver: bridge

⁠3. Dockerfile

The project uses a multi-stage Dockerfile to build and deploy the application. Here's a breakdown of the stages:

⁠Builder Stage:

This stage uses the official Go image to build the Nebula backend binary.

FROM golang:1.24.1-alpine AS builder

WORKDIR /app

RUN apk add --no-cache gcc musl-dev sqlite-dev git

COPY go.mod go.sum ./
RUN go mod download

COPY . .

ENV CGO_ENABLED=1
ENV GOOS=linux
ENV GOARCH=amd64

RUN go build -ldflags="-s -w" -o nebula-backend-server ./cmd/server/main.go

⁠Runtime Stage:

This stage uses the lightweight Alpine image for running the final application. It also includes SQLite libraries required for the app.

FROM alpine:latest

RUN apk add --no-cache sqlite-libs

RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

RUN mkdir -p /app/logs && chown -R appuser:appgroup /app

COPY --from=builder /app/nebula-backend-server .

USER appuser

EXPOSE 8080

ENTRYPOINT ["./nebula-backend-server"]

⁠4. Setting Up Environment Variables

Create a .env file from the provided .env.example and set the following critical environment variables:

cp .env.example .env

Edit the .env file:

• JWT_SECRET: A secret key used for JWT authentication.
• JWT_EXPIRATION_HOURS: Set the expiration time for JWTs (default is 24 hours).
• DATABASE_DIRECTORY: Path where the database files will be stored.
• DATABASE_DIRECTORY_FILE: Path to the central metadata database file.
• ALLOWED_ORIGINS: A list of frontend URLs that are allowed to make requests (space-separated).

⁠5. Building the Docker Image

To build the Docker image for the Nebula Backend, run the following command:

docker build -t nebula-backend .

⁠6. Running the Application with Docker Compose

Once the image is built, you can bring up the application using Docker Compose:

docker-compose up --build

This will:

• Start the nebula-backend service (with 5 replicas as specified).
• Start the nginx service to route external traffic to the backend.
• Expose the backend on port 8080 and Nginx on port 80.

⁠7. Accessing the Application

After the services are up and running, the backend API will be available on port 8080, and the Nginx reverse proxy will be available on port 80.

⁠8. Scaling the Backend

You can scale the backend service by modifying the replicas value in the docker-compose.yml file under the nebula-backend service and then redeploying the stack.

For example, to scale the backend to 10 replicas, change the replicas section:

deploy:
  replicas: 10

Then, run:

docker-compose up --scale nebula-backend=10

⁠9. Stopping and Removing Containers

To stop the services and remove the containers, use:

docker-compose down

This will stop and remove all containers defined in the docker-compose.yml file.

⁠Conclusion

This setup allows you to build and run the Nebula BaaS MVP in Docker containers, scale the backend service, and configure environment variables for a flexible deployment. You can also use Nginx as a reverse proxy to handle incoming traffic.