Introduction

Goma Gateway is a high-performance, security-focused API Gateway built for modern developers and cloud-native environments.
It combines an intuitive declarative configuration system with powerful middleware and first-class observability, helping you route, secure, and scale traffic effortlessly.

Whether you’re managing microservices, securing public APIs, or modernizing legacy systems, Goma Gateway delivers flexibility without unnecessary complexity.

Architecture:

Core Capabilities

Routing & Traffic Management

• Declarative YAML-based configuration

• Flexible routing for domains, hosts, paths, WebSocket, gRPC, TCP/UDP

• Multi-domain & multi-service support in one config

• Reverse proxy with backend abstraction

• Traffic control: rate limiting, load balancing, health checks

• Canary Deployments: Safely roll out new versions of your services with advanced canary deployment strategies:

  • Weighted Backends – Gradually shift traffic between service versions using percentage-based routing.

  • Conditional Routing – Route requests based on user groups, headers, query parameters, or cookies for targeted rollouts.

Security & Access Control

• Automatic HTTPS via Let’s Encrypt or custom TLS

• Mutual TLS (mTLS) for client certificate authentication

• Built-in authentication: Basic Auth, JWT, OAuth, LDAP, ForwardAuth

• CORS policies, header injection, fine-grained access control

• Exploit protection: SQL injection, XSS, and bot detection

• Method restrictions and regex-based URL rewriting

Performance & Reliability

• HTTP caching (in-memory or Redis) with smart invalidation

• Load balancing: round-robin, weighted, with health checks

• Scalable rate limiting: local or Redis-based (with automatic banning for repeated abuse)

Operations & Monitoring

• Zero-downtime config reloads

• Structured logging with configurable levels

• Prometheus/Grafana metrics

• Graceful error handling and backend failure interception

Cloud-Native Integration

• Kubernetes CRD support for native resource management

• GitOps-friendly with version-controlled configs

• Modular config files for organized route management

• Horizontal scalability & dynamic backend updates

Why Choose Goma Gateway?

Goma Gateway isn’t just another reverse proxy; it’s built for modern workflows:

• Simple, Declarative Configuration: Clean YAML config that’s easy to read, version-controlled, and automatable.

• First-Class Security: TLS, authentication, exploit protection, and access control baked in.

• Live Reload & GitOps-Ready: Perfect for CI/CD pipelines.

• Observability from Day One: Logging and metrics built in.

• Cloud-Native: Seamless integration with Kubernetes.

Perfect for: Public APIs, internal microservices, legacy modernization, or any project requiring secure, scalable traffic management.

Quick Tutorial: Deploying Goma Gateway as a Reverse Proxy for Docker Services

Prerequisites

Make sure you have:

• Docker installed

• Basic knowledge of YAML config

Step 1. Generate a Default Config

docker run --rm --name goma-gateway \
  -v "${PWD}/config:/etc/goma/" \
  jkaninda/goma-gateway config init --output /etc/goma/config.yml

This creates config/config.yml with default settings.

Step 2. Customize Your Configuration

Example config.yml:

version: 2
gateway:
  entryPoints:
    web:
      address: ":80"
    webSecure:
      address: ":443"
  routes:
    - path: /
      name: api
      hosts: ["api.example.com"]
      target: http://okapi-api:8080
      middlewares: ["basic-auth", "rate-limit"]

middlewares:
  - name: basic-auth
    type: basicAuth
    rule:
      users:
        - username: admin
          password: $2y$05$TIx7l8sJWvMFXw4n0GbkQuOhemPQOormacQC4W1p28TOVzJtx.XpO
  - name: rate-limit
    type: rateLimit
    rule:
      unit: minute
      requestsPerUnit: 60

certManager:
  acme:
    email: admin@example.com
    storageFile: /etc/letsencrypt/acme.json

Step 3. Run with Docker Compose

compose.yaml:

services:
  goma-gateway:
    image: jkaninda/goma-gateway
    command: -c config.yaml
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./config:/etc/goma/
      - ./letsencrypt:/etc/letsencrypt

  okapi-api:
    image: jkaninda/okapi-example
    restart: always

Your gateway is now live, ready to route, secure, and monitor your services.

Step 4. Grafana Dashboard

Goma Gateway includes built-in monitoring to track the health, performance, and behavior of your gateway and its routes.
Metrics are exposed in a Prometheus-compatible format, making them easy to integrate with Prometheus and visualize using Grafana.

A prebuilt Grafana dashboard is available for quick setup and visualization.
You can import it directly using:

Dashboard ID: 23799

Enable metrics

version: 2
gateway:
  # Timeout settings (in seconds)
  timeouts:
    write: 30
    read: 30
    idle: 30
  # Optional, default port 8080
  entryPoints:
    web:
      address: ":80"
    webSecure:
      address: ":443"
  monitoring:
    enableMetrics: true
    metricsPath: /metrics
  extraConfig:
    directory: /etc/goma/extra # Directory containing extra config files
    watch: false # Watch for changes in extra config directory and reload after changes

Dashboard Preview

Links

• GitHub: jkaninda/goma-gateway

• Docker Hub: jkaninda/goma-gateway

Securing a self-hosted Docker Registry is crucial, especially in production environments. LDAP (Lightweight Directory Access Protocol) is a widely adopted standard for managing user authentication and access control across services.

In this tutorial, we’ll use Goma Gateway to secure a Docker Registry using LLDAP for authentication. Goma makes it easy to protect routes with built-in middleware and declarative configuration.

Prerequisites

• Docker and Docker Compose installed

• Basic understanding of:

  • Docker networking

  • Reverse proxies

  • LDAP concepts

Architecture Overview

1. What Is Goma Gateway?

Goma Gateway is a lightweight, high-performance, and security-first API Gateway built for modern cloud-native infrastructure. With a developer-friendly configuration, Goma supports powerful middleware, observability, and advanced protocols out of the box.

Key Features

• Built-in authentication: Basic, JWT, OAuth2, LDAP, and ForwardAuth

• Rate limiting, HTTP caching, and bot detection

• Observability: Prometheus metrics, route health checks

• Protocol support: REST, gRPC, TCP, UDP

• TLS support: Let’s Encrypt and custom certificates

GitHub: jkaninda/goma-gateway

2. What Is LLDAP?

LLDAP is a lightweight, opinionated LDAP server designed to simplify authentication. It’s easy to deploy and comes with a minimal web UI for managing users and groups.

GitHub: lldap/lldap

3. Configure Local Hosts

Edit your /etc/hosts file to define virtual domains:

127.0.0.1 lldap.example.com registry.example.com okapi-api.example.com

Replace example.com With your domain, if needed.

4. Create a Docker Network

Create a shared Docker network for all services:

docker network create web

5. Docker Compose Setup

Create a compose.yaml file with the following services:

• gateway: Goma Gateway

• lldap: LDAP server

• registry: Docker Registry

• okapi-api: A test API service

services:
  gateway:
    image: jkaninda/goma-gateway
    container_name: gateway
    restart: always
    volumes:
      - ./goma.yml:/etc/goma/goma.yml
      - ./extra:/etc/goma/extra
      - ./certs:/etc/goma/certs
    ports:
      - 80:80
      - 443:443
    networks: [web]

  lldap:
    image: lldap/lldap:stable
    container_name: lldap
    restart: always
    environment:
      - UID=1
      - GID=1
      - TZ=Europe/Paris
      - LLDAP_JWT_SECRET=REPLACE_WITH_RANDOM
      - LLDAP_KEY_SEED=REPLACE_WITH_RANDOM
      - LLDAP_LDAP_BASE_DN=dc=example,dc=com
      - LLDAP_LDAP_USER_PASS=adminPasword
    ports:
      - "3890:3890"
    volumes:
      - data:/data
    networks: [web]

  registry:
    image: registry:3.0.0
    container_name: registry
    restart: always
    volumes:
      - registry:/var/lib/registry
    networks: [web]

  okapi-api:
    image: jkaninda/okapi-example
    container_name: okapi-api
    restart: always
    networks: [web]

volumes:
  data: {}
  registry: {}

networks:
  web:
    external: true

Important Security Notes:

1. Replace LLDAP_JWT_SECRET and LLDAP_KEY_SEED with strong random values

2. Change default LLDAP_LDAP_USER_PASS

6. Goma Gateway Configuration

Create a file named goma.yml in the project root:

version: 2
gateway:
  entryPoints:
    web:
      address: "[::]:80"
    webSecure:
      address: "[::]:443"
  tls:
    keys: []
    # Uncomment for custom certs:
    # - cert: /etc/goma/certs/cert.crt
    #   key: /etc/goma/certs/server.key.pem
  log:
    level: info
  networking:
    transport:
      insecureSkipVerify: true
  monitoring:
    enableMetrics: true
    metricsPath: /metrics
    enableLiveness: true
    enableRouteHealthCheck: true
    includeRouteHealthErrors: true
  extraConfig:
    directory: /etc/goma/extra
    watch: true

certManager:
  provider: acme
  acme:
    # Uncomment to enable Let’s Encrypt
    # email: admin@example.com
    storageFile: /etc/letsencrypt/acme.json

7. Define Routes and Middlewares

Create a folder named extra and add two files: routes.yml and middlewares.yml.

extra/routes.yml

routes:
  - name: lldap
    path: /
    hosts: [lldap.example.com]
    target: http://lldap:17170
    middlewares: [enforceHttps]

  - name: registry
    path: /
    hosts: [registry.example.com]
    rewrite: ''
    target: http://registry:5000
    middlewares: [enforceHttps]

  - name: okapi-api
    path: /
    hosts: [okapi-api.example.com]
    rewrite: ''
    target: http://okapi-api:8080
    middlewares: [enforceHttps]

extra/middlewares.yml

middlewares:
  - name: enforceHttps
    type: redirectScheme
    rule:
      scheme: https
      permanent: true

8. Deployment

Launch all services:

docker compose up -d

9. Insecure Registry Configuration

If you haven't configured TLS yet, Docker needs to allow connections to the insecure registry (development only):

Create or edit /etc/docker/daemon.json:

{
  "insecure-registries": ["registry.example.com"]
}

Restart Docker:

sudo systemctl restart docker

Tip: Use Let’s Encrypt or a custom certificate for production environments.

10. Access Your Services

• LDAP UI: https://lldap.example.com Login with admin / adminPasword. Then:

  • Create a group: registry_users

  • Create a user: bind_user (add to lldap_strict_readonly)

  • Create another user and assign them to registry_users

• Okapi API: https://okapi-api.example.com/api/books

• Docker Registry API: https://registry.example.com/v2/_catalog

11. Enable LDAP Authentication

Update middlewares.yml with LDAP auth middleware:

  - name: ldap-auth
    type: ldap
    paths:
      - /.*
    rule:
      forwardUsername: true
      realm: restricted
      url: ldap://lldap:3890
      baseDN: dc=example,dc=com
      bindDN: uid=bind_user,ou=people,dc=example,dc=com
      bindPass: bind_user_password
      userFilter: "(&(objectclass=person)(memberof=cn=registry_users,ou=groups,dc=example,dc=com)(uid=%s))"
      startTLS: false
      insecureSkipVerify: true
      connPool:
        size: 150
        burst: 100
        ttl: 30s

Then apply it in routes.yml:

  - name: registry
    path: /
    hosts: [registry.example.com]
    rewrite: ''
    target: http://registry:5000
    middlewares:
      - enforceHttps
      - ldap-auth

  - name: okapi-api
    path: /
    hosts: [okapi-api.example.com]
    rewrite: ''
    target: http://okapi-api:8080
    middlewares:
      - enforceHttps
      - ldap-auth

12. Test the Registry

Pull the Nginx image:

docker pull nginx:latest

Tag the image:

docker tag nginx:latest registry.example.com/nginx:latest

Push to your registry:

docker push registry.example.com/nginx:latest

You should be prompted for credentials, and only LDAP-authorized users will be able to push or pull.

Conclusion

You’ve successfully secured your Docker Registry using Goma Gateway and LLDAP. With just a few declarative configs and containers, you now have a robust, LDAP-backed authentication layer for your registry and a reusable pattern for protecting any internal API or service.

Feel free to extend this setup to protect other services and APIs with Goma’s flexible middleware system.

Go (or Golang) is increasingly favored for backend development due to its performance, simplicity, and concurrency features.

In this tutorial, we’ll walk through building a REST API using the Okapi framework—a modern, minimalist web framework for Go that emphasizes developer experience and clean API design.

What is Okapi?

Okapi is a lightweight, performant web framework inspired by FastAPI. It is designed to help developers build scalable, well-documented APIs quickly, with minimal boilerplate.

Key features:

• Minimalist syntax: Clean and declarative route definitions.

• OpenAPI integration: Automatic and real-time OpenAPI spec generation.

• Extensible middleware: Support for custom and built-in middleware like JWTAuth.

Why use Okapi?

• Easy to Learn – With familiar Go syntax and intuitive APIs, you can be productive in minutes, even on your first project.

• Lightweight and Unopinionated – Okapi is built from the ground up and doesn’t wrap or build on top of another framework. It gives you full control without unnecessary abstraction or bloat.

• Highly Flexible – Designed to adapt to your architecture and workflow, not the other way around.

• Built for Production – Fast, reliable, and efficient under real-world load. Okapi is optimized for performance without sacrificing developer experience.

• Standard Library Compatibility - Integrates seamlessly with Go’s net/http standard library, making it easy to combine Okapi with existing Go code and tools.

• Automatic OpenAPI Documentation - Generate comprehensive OpenAPI specs automatically for every route, keeping your API documentation always up to date with your code.

• Dynamic Route Management - Enable or disable routes and route groups at runtime. No need to comment out code—just toggle behavior cleanly and efficiently.

Ideal for:

• High-performance REST APIs

• Composable microservices

• Rapid prototyping

• Learning & teaching Go web development

Whether you're building your next startup, internal tools, or side projects, Okapi scales with you.

Prerequisites

Before you begin, ensure you have the following installed:

• Basic knowledge of Go

• Go installed (v1.24+ recommended)

• A code editor (VS Code or similar)

Project Setup

Start by creating your project directory and initializing Go modules:

mkdir okapi-example && cd okapi-example
go mod init okapi-example
go get github.com/jkaninda/okapi@latest

Project folder structure:

okapi-example/
├── controllers
│   └── controller.go
├── go.mod
├── go.sum
├── main.go
├── middlewares
│   └── middleware.go
├── models
│   └── model.go
└── routes
    └── route.go

Basic Routing Example

Here’s a minimal Okapi server that responds with a welcome message:

package main

import (
    "github.com/jkaninda/okapi"
)

func main() {
    o := okapi.Default()

    o.Get("/", func(c okapi.Context) error {
        return c.OK(okapi.M{"message": "Hello from Okapi Web Framework!", "License": "MIT"})
    })

    o.Get("/greet/:name", func(c okapi.Context) error {
        name := c.Param("name")
        return c.OK(okapi.M{"message": "Hello, " + name + "!"})
    })

    if err := o.Start(); err != nil {
        panic(err)
    }
}

Run it with:

go run main.go

Visit http://localhost:8080 to see the response.

Building a Book API

We’ll now create a simple API to manage books, including authentication for admin-level routes.

1. Define Models

models/model.go:

package models

type Response struct {
    Success bool   `json:"success"`
    Message string `json:"message"`
    Data    Book   `json:"data"`
}
type Book struct {
    Id    int    `json:"id"`
    Name  string `json:"name" form:"name"  max:"50" required:"true" description:"Book name"`
    Price int    `json:"price" form:"price" query:"price" yaml:"price" required:"true" description:"Book price"`
}
type ErrorResponse struct {
    Success bool `json:"success"`
    Status  int  `json:"status"`
    Details any  `json:"details"`
}

type AuthRequest struct {
    Username string `json:"username" required:"true" description:"Username for authentication"`
    Password string `json:"password" required:"true" description:"Password for authentication"`
}
type AuthResponse struct {
    Success   bool   `json:"success"`
    Message   string `json:"message"`
    Token     string `json:"token,omitempty"`
    ExpiresAt int64  `json:"expires,omitempty"`
}
type UserInfo struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Role  string `json:"role"`
}

2. Implement Middleware (JWT)

middlewares/middleware.go:

Uses Okapi's built-in JWTAuth with claim validation and token generation.

package middlewares

import (
    "errors"
    "fmt"
    "github.com/golang-jwt/jwt/v5"
    "github.com/jkaninda/okapi"
    "github.com/jkaninda/okapi/examples/route-definition/models"
    "log/slog"
    "net/http"
    "strings"
    "time"
)

var (
    // signingSecret is used to sign the JWT tokens
    signingSecret = "supersecret"

    JWTAuth = &okapi.JWTAuth{
        SigningSecret:    []byte(signingSecret),
        TokenLookup:      "header:Authorization",
        ClaimsExpression: "Equals(`email_verified`, `true`) && Equals(`user.role`, `admin`) && Contains(`permissions`, `create`, `delete`, `update`)",
        ForwardClaims: map[string]string{
            "email": "user.email",
            "role":  "user.role",
            "name":  "user.name",
        },
        // CustomClaims claims validation function
        ValidateClaims: func(c okapi.Context, claims jwt.Claims) error {
            slog.Info("Validating JWT claims for role using custom function")
            // Simulate a custom claims validation
            mapClaims, ok := claims.(jwt.MapClaims)
            if !ok {
                return errors.New("invalid claims type")
            }
            if role, exist := mapClaims["user"].(map[string]interface{})["role"]; exist {
                fmt.Println("Role from claims:", role)
            }
            return nil
        },
    }
    jwtClaims = jwt.MapClaims{
        "sub": "12345",
        "iss": "okapi.example.com",
        "aud": "okapi.example.com",
        "user": map[string]string{
            "name":  "",
            "role":  "",
            "email": "",
        },
        "email_verified": true,
        "permissions":    []string{"read", "create"},
        "exp":            time.Now().Add(2 * time.Hour).Unix(),
    }
    adminPermissions = []string{"read", "create", "delete", "update"}
)

func Login(authRequest *models.AuthRequest) (models.AuthResponse, error) {
    // This is where you would typically validate the user credentials against a database

    slog.Info("Login attempt", "username", authRequest.Username)
    // Simulate a login function that returns a JWT token
    if authRequest.Username != "admin" && authRequest.Password != "password" ||
        authRequest.Username != "user" && authRequest.Password != "password" {
        return models.AuthResponse{
            Success: false,
            Message: "Invalid username or password",
        }, fmt.Errorf("username or password is wrong")
    }

    if _, ok := jwtClaims["user"].(map[string]string); ok {
        jwtClaims["user"].(map[string]string)["name"] = strings.ToUpper(authRequest.Username)
        jwtClaims["user"].(map[string]string)["role"] = authRequest.Username
        jwtClaims["user"].(map[string]string)["email"] = authRequest.Username + "@example.com"
        jwtClaims["permissions"] = []string{"read"}

        // If the user is an admin, add admin permissions
        if authRequest.Username == "admin" {
            jwtClaims["permissions"] = adminPermissions
        }

    }
    // Set the expiration time for the JWT token
    expireAt := 30 * time.Minute
    jwtClaims["exp"] = time.Now().Add(expireAt).Unix()

    token, err := okapi.GenerateJwtToken(JWTAuth.SigningSecret, jwtClaims, expireAt)
    if err != nil {

        return models.AuthResponse{
            Success: false,
            Message: "Invalid username or password",
        }, fmt.Errorf("failed to generate JWT token: %w", err)
    }
    return models.AuthResponse{
        Success:   true,
        Message:   "Welcome back " + authRequest.Username,
        Token:     token,
        ExpiresAt: time.Now().Add(expireAt).Unix(),
    }, nil

}
func CustomMiddleware(next okapi.HandleFunc) okapi.HandleFunc {
    return func(c okapi.Context) error {
        slog.Info("Custom middleware executed", "path", c.Request().URL.Path, "method", c.Request().Method)
        // You can add any custom logic here, such as logging, authentication, etc.
        // For example, let's log the request method and URL
        slog.Info("Request received", "method", c.Request().Method, "url", c.Request().URL.String())
        // Call the next handler in the chain
        if err := next(c); err != nil {
            // If an error occurs, log it and return a generic error response
            slog.Error("Error in custom middleware", "error", err)
            return c.JSON(http.StatusInternalServerError, okapi.M{"error": "Internal Server Error"})
        }
        return nil
    }
}

3. Create Controllers

controllers/controller.go:

Implements handlers for Home, Book, and Authentication logic.

package controllers

import (
    "fmt"
    "github.com/jkaninda/okapi"
    "net/http"
    "okapi-example/middlewares"
    "okapi-example/models"
    "strconv"
)

type BookController struct{}
type CommonController struct{}
type AuthController struct{}

var (
    books = []*models.Book{
        {Id: 1, Name: "The Go Programming Language ", Price: 100},
        {Id: 2, Name: "Building REST/API With Okapi ", Price: 50},
        {Id: 3, Name: "Learning Go", Price: 200},
        {Id: 4, Name: "Go Web Programming", Price: 300},
        {Id: 5, Name: "Go in Action", Price: 150},
    }
    ApiVersion = "V1"
)

// ****************** Controllers *****************

func (hc *CommonController) Home(c okapi.Context) error {
    return c.OK(okapi.M{"message": "Welcome to the Okapi Web Framework!"})
}
func (hc *CommonController) Version(c okapi.Context) error {
    return c.OK(okapi.M{"version": ApiVersion})
}
func (bc *BookController) GetBooks(c okapi.Context) error {
    // Simulate fetching books from a database
    return c.OK(books)
}

func (bc *BookController) CreateBook(c okapi.Context) error {
    // Simulate creating a book in a database
    book := &models.Book{}
    err := c.Bind(book)
    if err != nil {
        return c.ErrorBadRequest(models.ErrorResponse{Success: false, Status: http.StatusBadRequest, Details: err.Error()})
    }
    book.Id = len(books) + 1
    books = append(books, book)
    response := models.Response{
        Success: true,
        Message: "Book created successfully",
        Data:    *book,
    }
    return c.OK(response)
}
func (bc *BookController) GetBook(c okapi.Context) error {
    id := c.Param("id")
    i, err := strconv.Atoi(id)
    if err != nil {
        return c.ErrorBadRequest(models.ErrorResponse{Success: false, Status: http.StatusBadRequest, Details: err.Error()})
    }
    // Simulate a fetching book from a database

    for _, book := range books {
        if book.Id == i {
            return c.OK(book)
        }
    }
    return c.AbortNotFound("Book not found")
}
func (bc *BookController) DeleteBook(c okapi.Context) error {
    id := c.Param("id")
    i, err := strconv.Atoi(id)
    if err != nil {
        return c.ErrorBadRequest(models.ErrorResponse{Success: false, Status: http.StatusBadRequest, Details: err.Error()})
    }

    // Simulate deleting a book from a database
    for index, book := range books {
        if book.Id == i {
            books = append(books[:index], books[index+1:]...)
            return c.OK(models.Response{
                Success: true,
                Message: "Book deleted successfully",
            })
        }
    }
    return c.AbortNotFound("Book not found")
}

// ******************** AuthController *****************

func (bc *AuthController) Login(c okapi.Context) error {
    authRequest := &models.AuthRequest{}
    err := c.Bind(authRequest)
    if err != nil {
        return c.ErrorBadRequest(models.ErrorResponse{Success: false, Status: http.StatusBadRequest, Details: err.Error()})
    }
    // Validate the authRequest and generate a JWT token
    authResponse, err := middlewares.Login(authRequest)
    if err != nil {
        return c.ErrorUnauthorized(authResponse)
    }
    return c.OK(authResponse)
}
func (bc *AuthController) WhoAmI(c okapi.Context) error {
    //Get User Information from the context, shared by the JWT middleware using forwardClaims
    email := c.GetString("email")
    if email == "" {
        return c.AbortUnauthorized("Unauthorized", fmt.Errorf("user not authenticated"))
    }

    // Respond with the current user information
    return c.OK(models.UserInfo{
        Email: email,
        Role:  c.GetString("role"),
        Name:  c.GetString("name"),
    },
    )
}

4. Define Routes

routes/route.go:

Group routes by feature and use route definitions with OpenAPI documentation metadata.

package routes

import (
    "net/http"
    "okapi-example/controllers"
    "okapi-example/middlewares"
    "okapi-example/models"

    "github.com/jkaninda/okapi"
)

// ****************** Controllers ******************
var (
    bookController   = &controllers.BookController{}
    commonController = &controllers.CommonController{}
    authController   = &controllers.AuthController{}
)

type Route struct {
    // app is the Okapi application
    app *okapi.Okapi
}

// NewRoute creates a new Route instance with the Okapi application
func NewRoute(app *okapi.Okapi) *Route {
    // Update OpenAPI documentation with the application title and version
    app.WithOpenAPIDocs(okapi.OpenAPI{
        Title:   "REST APIs with Okapi Framework",
        Version: controllers.ApiVersion,
        Licence: okapi.License{
            Name: "MIT",
            URL:  "https://opensource.org/license/mit/",
        },
    })
    return &Route{
        app: app,
    }
}

// ****************** Routes Definition ******************

// Home returns the route definition for the Home endpoint
func (r *Route) Home() okapi.RouteDefinition {
    return okapi.RouteDefinition{
        Path:    "/",
        Method:  http.MethodGet,
        Handler: commonController.Home,
        Group:   &okapi.Group{Prefix: "/", Tags: []string{"CommonController"}},
        Options: []okapi.RouteOption{
            okapi.DocSummary("Home"),
            okapi.DocDescription("Welcome to the Okapi Web Framework!"),
        },
    }
}

// Version returns the route definition for the Version endpoint
func (r *Route) Version() okapi.RouteDefinition {
    return okapi.RouteDefinition{
        Path:    "/version",
        Method:  http.MethodGet,
        Handler: commonController.Version,
        Group:   &okapi.Group{Prefix: "/api/v1", Tags: []string{"CommonController"}},
        Options: []okapi.RouteOption{
            okapi.DocSummary("API Version"),
            okapi.DocDescription("Get the API version"),
            okapi.DocResponse(okapi.M{"version": "v1"}),
        },
    }
}

// ************* Book Routes *************
// In this section, we will make BookRoutes deprecated and create BookV1Routes

// BookRoutes returns the route definitions for the BookController
func (r *Route) BookRoutes() []okapi.RouteDefinition {
    apiGroup := &okapi.Group{Prefix: "/api", Tags: []string{"BookController"}}
    // Mark the group as deprecated
    // But, it will still be available for use, it's just marked as deprecated on the OpenAPI documentation
    apiGroup.Deprecated()
    // Apply custom middleware
    apiGroup.Use(middlewares.CustomMiddleware)
    return []okapi.RouteDefinition{
        {
            Method:  http.MethodGet,
            Path:    "/books",
            Handler: bookController.GetBooks,
            Group:   apiGroup,
            Options: []okapi.RouteOption{
                okapi.DocSummary("Get Books"),
                okapi.DocDescription("Retrieve a list of books"),
                okapi.DocResponse([]models.Book{}),
                okapi.DocResponse(http.StatusBadRequest, models.ErrorResponse{}),
                okapi.DocResponse(http.StatusNotFound, models.ErrorResponse{}),
            },
        },
        {
            Method:  http.MethodGet,
            Path:    "/books/:id",
            Handler: bookController.GetBook,
            Group:   apiGroup,
            Options: []okapi.RouteOption{
                okapi.DocSummary("Get Book by ID"),
                okapi.DocDescription("Retrieve a book by its ID"),
                okapi.DocPathParam("id", "int", "The ID of the book"),
                okapi.DocResponse(models.Book{}),
                okapi.DocResponse(http.StatusBadRequest, models.ErrorResponse{}),
                okapi.DocResponse(http.StatusNotFound, models.ErrorResponse{}),
            },
        },
    }
}

// *************** End of Book Routes ***************

// *********************** Book v1 Routes ***********************

func (r *Route) V1BookRoutes() []okapi.RouteDefinition {
    apiGroup := &okapi.Group{Prefix: "/api"}
    apiV1Group := apiGroup.Group("/v1").WithTags([]string{"BookController"})
    // Apply custom middleware
    apiGroup.Use(middlewares.CustomMiddleware)
    return []okapi.RouteDefinition{
        {
            Method:  http.MethodGet,
            Path:    "/books",
            Handler: bookController.GetBooks,
            Group:   apiV1Group,
            Options: []okapi.RouteOption{
                okapi.DocSummary("Get Books"),
                okapi.DocDescription("Retrieve a list of books"),
                okapi.DocResponse([]models.Book{}),
                okapi.DocResponse(http.StatusBadRequest, models.ErrorResponse{}),
            },
        },
        {
            Method:  http.MethodGet,
            Path:    "/books/:id",
            Handler: bookController.GetBook,
            Group:   apiV1Group,
            Options: []okapi.RouteOption{
                okapi.DocSummary("Get Book by ID"),
                okapi.DocDescription("Retrieve a book by its ID"),
                okapi.DocPathParam("id", "int", "The ID of the book"),
                okapi.DocResponse(models.Book{}),
                okapi.DocResponse(http.StatusBadRequest, models.ErrorResponse{}),
                okapi.DocResponse(http.StatusNotFound, models.ErrorResponse{}),
            },
        },
    }
}

// *************** Auth Routes ****************

func (r *Route) AuthRoute() okapi.RouteDefinition {
    apiGroup := &okapi.Group{Prefix: "/api/v1/auth", Tags: []string{"AuthController"}}
    apiGroup.Use(middlewares.CustomMiddleware)
    return okapi.RouteDefinition{

        Method:  http.MethodPost,
        Path:    "/login",
        Handler: authController.Login,
        Group:   apiGroup,
        Options: []okapi.RouteOption{
            okapi.DocSummary("Login"),
            okapi.DocDescription("User login to get a JWT token"),
            okapi.DocRequestBody(models.AuthRequest{}),
            okapi.DocResponse(models.AuthResponse{}),
            okapi.DocResponse(http.StatusUnauthorized, models.AuthResponse{}),
        },
    }
}

// ************** Authenticated Routes **************

func (r *Route) SecurityRoutes() []okapi.RouteDefinition {
    coreGroup := &okapi.Group{Prefix: "/api/v1/security", Tags: []string{"SecurityController"}}
    // Apply JWT authentication middleware to the admin group
    coreGroup.Use(middlewares.JWTAuth.Middleware)
    // Apply custom middleware
    coreGroup.Use(middlewares.CustomMiddleware)
    coreGroup.WithBearerAuth() //Enable Bearer token for OpenAPI documentation
    return []okapi.RouteDefinition{
        {
            Method:  http.MethodPost,
            Path:    "/whoami",
            Handler: authController.WhoAmI,
            Group:   coreGroup,
            Options: []okapi.RouteOption{
                okapi.DocSummary("Whoami"),
                okapi.DocDescription("Get the current user's information"),
                okapi.DocResponse(models.UserInfo{}),
            },
        },
    }
}

// ***************** Admin Routes *****************

func (r *Route) AdminRoutes() []okapi.RouteDefinition {
    apiGroup := &okapi.Group{Prefix: "/api/v1/admin", Tags: []string{"AdminController"}}
    // Apply JWT authentication middleware to the admin group
    apiGroup.Use(middlewares.JWTAuth.Middleware)
    apiGroup.Use(middlewares.CustomMiddleware)
    apiGroup.WithBearerAuth() //Enable Bearer token for OpenAPI documentation

    return []okapi.RouteDefinition{

        {
            Method:  http.MethodPost,
            Path:    "/books",
            Handler: bookController.CreateBook,
            Group:   apiGroup,
            Options: []okapi.RouteOption{
                okapi.DocSummary("Create Book"),
                okapi.DocDescription("Create a new book"),
                okapi.DocRequestBody(models.Book{}),
                okapi.DocResponse(models.Response{}),
            },
        },
        {
            Method:  http.MethodDelete,
            Path:    "/books/:id",
            Handler: bookController.DeleteBook,
            Group:   apiGroup,
            Options: []okapi.RouteOption{
                okapi.DocSummary("Delete Book by ID"),
                okapi.DocDescription("Delete a book by its ID"),
                okapi.DocPathParam("id", "int", "The ID of the book"),
                okapi.DocResponse(models.Response{}),
                okapi.DocResponse(http.StatusNotFound, models.ErrorResponse{}),
                okapi.DocResponse(http.StatusUnauthorized, models.ErrorResponse{}),
            },
        },
    }
}

5. Main Entry Point

main.go:

package main

import (
    "github.com/jkaninda/okapi"
    "okapi-example/routes"
)

func main() {
    app := okapi.Default()

    // Create the route instance
    route := routes.NewRoute(app)
    // Register routes
    app.Register(route.Home())
    app.Register(route.Version())
    app.Register(route.AdminRoutes()...)
    app.Register(route.AuthRoute())
    app.Register(route.SecurityRoutes()...)
    app.Register(route.BookRoutes()...)
    app.Register(route.V1BookRoutes()...)

    // Start the server
    if err := app.Start(); err != nil {
        panic(err)
    }

}

Run the Server

go run main.go

Access the API

• Visit: http://localhost:8080

• Swagger UI: http://localhost:8080/docs

Example response:

{
  "message": "Welcome to the Okapi Web Framework!"
}

Swagger UI

Summary

With Okapi, you can create well-structured, RESTful APIs in Go with minimal effort. Features like declarative routing, built-in JWT authentication, and automatic OpenAPI documentation make it ideal for modern backend development.

Okapi Github: https://github.com/jkaninda/okapi

Source code: https://github.com/jkaninda/okapi/tree/main/examples/route-definition

Next Steps

• Add database integration (e.g., PostgreSQL with GORM)

• Integrate unit tests

• Deploy to Docker or cloud platforms

• Secure your JWT secrets using environment variables

🔐 What is S3Safe?

S3Safe is an open-source command-line tool designed for efficient, and flexible backup and restore operations involving Amazon S3 and any S3-compatible storage (e.g., Wasabi, MinIO, etc.). Whether you're backing up application data, logs, or system snapshots, S3Safe offers a clean and intuitive interface to handle these tasks reliably.

🔑 Key Features

✅ Compression Support – Backup with gzip/tar compression to save space.
✅ Flexible Operations – Backup entire directories, single files, or use recursive operations.
✅ Exclusion Patterns – Skip unwanted files during backup.
✅ Docker Support – Run S3Safe in containerized environments.

🚀 Installation

Via Go

go install github.com/jkaninda/s3safe@latest

Via Docker

docker pull jkaninda/s3safe:latest

⚙️ Configuration

Copy .env.example to .env and configure your S3 credentials:

AWS_REGION=us-east-1
AWS_ENDPOINT=https://s3.wasabisys.com  # For S3-compatible storage
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_KEY=your_secret_key
AWS_BUCKET=your_bucket_name
AWS_FORCE_PATH="true"  # Required for path-style URLs
AWS_DISABLE_SSL="false"  # Set "true" for non-HTTPS endpoints

🛠️ Command Overview

Global Options

Backup Options

Restore Options

💡 Usage Examples

Backup Operations

Backup a directory (compressed with timestamp):

s3safe backup -p ./backups -d /s3path --compress --timestamp

Backup a single file:

s3safe backup --file data.db --dest /s3path/db-backups --compress

Non-compressed recursive backup:

s3safe backup -p ./backups -d /s3path/backups -r

Restore Operations

Restore & decompress a backup:

s3safe restore -p /s3path/backup.tar.gz -d ./restored --decompress

Restore a directory (recursive):

s3safe restore --path /s3path --dest ./restored --recursive

🐳 Running with Docker

There is no need to install Go or manage dependencies locally—just run it in Docker:

Backup with Docker:

docker run --rm --env-file .env \
  -v "./backups:/backups" \
  jkaninda/s3safe:latest \
  backup --path /backups -d s3path --compress

Restore with Docker:

docker run --rm --env-file .env \
  -v "./restored:/restored" \
  jkaninda/s3safe:latest \
  restore --path s3path/backup.tar.gz -d /restored --decompress

🔗 GitHub: https://github.com/jkaninda/s3safe

🚀 Happy Backing Up! 🚀

PG-BKUP is a powerful container image designed to simplify the backup, restore, and migration of PostgreSQL databases. It supports multiple storage options, including local storage, S3, SFTP, and Azure Blob, and ensures data security through GPG encryption. Whether you're managing a single database or multiple databases, PG-BKUP offers the flexibility and reliability you need.

Prerequisites

Before diving into the backup process, ensure the following are in place:

• A running Kubernetes cluster.
• A PostgreSQL database deployed in Kubernetes.
• (Optional) S3-compatible, SFTP, or Azure Blob storage for remote backups.

Backup Strategies with PG-BKUP

PG-BKUP can be deployed on Kubernetes as a Job, CronJob, or Deployment using its integrated scheduled mode. Below, we’ll explore two common approaches: using a CronJob for scheduled backups and a Deployment for backing up multiple databases.

1. Backup Using a Kubernetes CronJob

A CronJob is ideal for scheduling regular backups, such as nightly backups. Here’s how to set it up:

Step 1: Create a Kubernetes Secret

Store sensitive information like database credentials and AWS keys in a Kubernetes Secret. Use the following commands to encode your credentials:

echo -n "username" | base64
echo -n "password" | base64

Then, create a Kubernetes Secret YAML file:

apiVersion: v1
kind: Secret
metadata:
  name: backup-secret
type: Opaque
data:
  username: dXNlcm5hbWU=  # Replace with your base64-encoded username
  password: cGFzc3dvcmQ=  # Replace with your base64-encoded password
  aws_access_key_id: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4  # Replace with your base64-encoded AWS access key
  aws_secret_access_key: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4  # Replace with your base64-encoded AWS secret key

Step 2: Define the CronJob

Create a CronJob YAML file to schedule nightly backups:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: backup-job
spec:
  schedule: "0 0 * * *"  # Runs at midnight every day
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: pg-bkup
            image: jkaninda/pg-bkup
            command:
            - /bin/sh
            - -c
            - backup --storage s3 --path /backups
            env:
            - name: DB_PORT
              value: "5432"
            - name: DB_HOST
              value: "postgres"
            - name: DB_NAME
              value: "mydb"
            - name: DB_USERNAME
              valueFrom:
                secretKeyRef:
                  name: backup-secret
                  key: username
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: backup-secret
                  key: password
            - name: AWS_S3_ENDPOINT
              value: "https://s3.amazonaws.com"
            - name: AWS_S3_BUCKET_NAME
              value: "mybucket"
            - name: AWS_REGION
              value: "us-east-1"
            - name: AWS_DISABLE_SSL
              value: "false"
            - name: AWS_FORCE_PATH_STYLE
              value: "false"
            - name: AWS_ACCESS_KEY_ID
              valueFrom:
                secretKeyRef:
                  name: backup-secret
                  key: aws_access_key_id
            - name: AWS_SECRET_ACCESS_KEY
              valueFrom:
                secretKeyRef:
                  name: backup-secret
                  key: aws_secret_access_key
          restartPolicy: Never

Optional: Enable Backup Encryption

PG-BKUP supports GPG encryption for added security. To encrypt your backups, include the GPG_PASSPHRASE or GPG_PUBLIC_KEY environment variable in the CronJob configuration.

2. Backup Multiple Databases Using a Deployment

If you’re managing multiple databases, you can use a single Kubernetes Deployment to back them up. Here’s how:

Step 1: Create a ConfigMap

Define the configuration for multiple databases in a ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: backup-config
data:
  config.yaml: |
    cronExpression: "@daily"  # Optional: Schedule backups daily
    databases:
      - host: postgres1
        port: 5432
        name: database1
        user: database1
        password: password
        path: /s3-path/database1

      - host: postgres2
        port: 5432
        name: lldap
        user: lldap
        password: password
        path: /s3-path/lldap

      - host: postgres3
        port: 5432
        name: keycloak
        user: keycloak
        password: password
        path: /s3-path/keycloak

      - host: postgres4
        port: 5432
        name: joplin
        user: joplin
        password: password
        path: /s3-path/joplin

Step 2: Define the Deployment

Create a Deployment YAML file to manage the backups:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backups
spec:
  selector:
    matchLabels:
      app: backups
  template:
    metadata:
      labels:
        app: backups
    spec:
      containers:
      - name: pg-bkup
        image: jkaninda/pg-bkup
        command: ["backup", "--storage", "s3", "--path", "/backups", "--config", "/config/config.yaml"]
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"
        env:
            - name: AWS_S3_ENDPOINT
              value: "https://s3.amazonaws.com"
            - name: AWS_S3_BUCKET_NAME
              value: "mybucket"
            - name: AWS_REGION
              value: "us-east-1"
            - name: AWS_DISABLE_SSL
              value: "false"
            - name: AWS_FORCE_PATH_STYLE
              value: "false"
            - name: AWS_ACCESS_KEY_ID
              valueFrom:
                secretKeyRef:
                  name: backup-secret
                  key: aws_access_key_id
            - name: AWS_SECRET_ACCESS_KEY
              valueFrom:
                secretKeyRef:
                  name: backup-secret
                  key: aws_secret_access_key
        volumeMounts:
        - name: config
          mountPath: "/config"
          readOnly: true
      volumes:
      - name: config
        configMap:
          name: backup-config

Optional: Enable Notifications

If you enable backupRescueMode (which allows backups to proceed even if one database is down), consider setting up notifications to alert you of any backup failures.

Conclusion

Automating Postgres database backups in Kubernetes using PG-BKUP is a robust and efficient way to ensure your data is secure and recoverable. With support for multiple storage options (local, S3, SFTP, and Azure Blob) and GPG encryption, PG-BKUP provides unparalleled flexibility and security. By implementing these strategies, you can safeguard your critical data and minimize downtime in case of unexpected failures.

For more detailed instructions and advanced configurations, explore the official documentation: PG-BKUP Documentation.

This guide provides a comprehensive walkthrough on automating backups for multiple MySQL databases running inside Docker containers using the Mysql-bkup tool. With Mysql-bkup, you can streamline the process, making it easier and more efficient to manage backups for multiple databases simultaneously.

Why Backing Up Multiple Databases is Challenging

• Complexity: Managing individual backup scripts for each database can be time-consuming and error-prone.
• Resource Management: Running multiple backup processes simultaneously can strain system resources.
• Consistency: Ensuring all databases are backed up at the same time and with the same settings can be difficult.

How Mysql-bkup Simplifies the Process

Mysql-bkup is a Docker-based tool designed to backup, restore, and migrate MySQL databases. It supports multiple databases, and storage options (local, S3, SFTP, Azure Blob), and ensures data security through GPG encryption. With its configuration file, you can define backup schedules and settings for multiple databases in one place, eliminating the need for individual scripts.

Key Benefits of Using Mysql-bkup

• Centralized Configuration: Manage backups for multiple databases using a single configuration file.
• Flexible Scheduling: Set up global or database-specific backup schedules with cron expressions.
• Multiple Storage Options: Store backups locally or in the cloud (S3, Azure Blob, SFTP).
• Security: Encrypt backups using GPG for added protection.
• Notifications: Receive email or Telegram alerts for backup success or failure.

Getting Started

Prerequisites

Before proceeding, ensure the following are in place:

• Docker installed and running.
• MySQL or MariaDB databases running in Docker containers.

Automating Backups for Multiple Databases

Mysql-bkup allows you to configure and automate backups for multiple databases using a configuration file. This file defines the backup settings for each database, including host, port, credentials, and storage paths.

Configuration File Setup

The configuration file can be mounted into the container at /config/config.yaml, /config/config.yml, or specified via the BACKUP_CONFIG_FILE environment variable.

Key Features:

• Global Environment Variables: Use these for databases that share the same configuration.
• Database-Specific Overrides: Override global settings for individual databases by specifying them in the configuration file or using the database name as a suffix in the variable name (e.g., DB_HOST_DATABASE1).
• Global Cron Expression: Define a global cronExpression in the configuration file to schedule backups for all databases. If omitted, backups will run immediately.
• Configuration File Path: Specify the configuration file path using:
  • The BACKUP_CONFIG_FILE environment variable.
  • The --config or -c flag for the backup command.

Example Configuration File (config.yaml)

# Optional: Define a global cron expression for scheduled backups.
# Example: "@every 20m" (runs every 20 minutes). If omitted, backups run immediately.
cronExpression: "@midnight" # Optional

databases:
  - host: mysql1       # Optional: Overrides DB_HOST or uses DB_HOST_DATABASE1.
    port: 3306         # Optional: Default is 3306. Overrides DB_PORT or uses DB_PORT_DATABASE1.
    name: database1    # Required: Database name.
    user: database1    # Optional: Overrides DB_USERNAME or uses DB_USERNAME_DATABASE1.
    password: password # Optional: Overrides DB_PASSWORD or uses DB_PASSWORD_DATABASE1.
    path: /s3-path/database1  # Required: Backup path for SSH, FTP, or S3 (e.g., /home/toto/backup/).

  - host: mysql2       # Optional: Overrides DB_HOST or uses DB_HOST_LLAP.
    port: 3306         # Optional: Default is 3306. Overrides DB_PORT or uses DB_PORT_LLAP.
    name: lldap        # Required: Database name.
    user: lldap        # Optional: Overrides DB_USERNAME or uses DB_USERNAME_LLAP.
    password: password # Optional: Overrides DB_PASSWORD or uses DB_PASSWORD_LLAP.
    path: /s3-path/lldap  # Required: Backup path for SSH, FTP, or S3 (e.g., /home/toto/backup/).

  - host: mysql3       # Optional: Overrides DB_HOST or uses DB_HOST_KEYCLOAK.
    port: 3306         # Optional: Default is 3306. Overrides DB_PORT or uses DB_PORT_KEYCLOAK.
    name: keycloak     # Required: Database name.
    user: keycloak     # Optional: Overrides DB_USERNAME or uses DB_USERNAME_KEYCLOAK.
    password: password # Optional: Overrides DB_PASSWORD or uses DB_PASSWORD_KEYCLOAK.
    path: /s3-path/keycloak  # Required: Backup path for SSH, FTP, or S3 (e.g., /home/toto/backup/).

  - host: mysql4       # Optional: Overrides DB_HOST or uses DB_HOST_JOPLIN.
    port: 3306         # Optional: Default is 3306. Overrides DB_PORT or uses DB_PORT_JOPLIN.
    name: joplin       # Required: Database name.
    user: joplin       # Optional: Overrides DB_USERNAME or uses DB_USERNAME_JOPLIN.
    password: password # Optional: Overrides DB_PASSWORD or uses DB_PASSWORD_JOPLIN.
    path: /s3-path/joplin  # Required: Backup path for SSH, FTP, or S3 (e.g., /home/toto/backup/).

Deploying with Docker Compose

To deploy the backup solution using Docker Compose, create a compose.yaml file with the following content:

services:
  mysql-bkup:
    image: jkaninda/mysql-bkup
    container_name: mysql-bkup
    command: backup --config /backup/config.yaml
    volumes:
      - ./backup:/backup  # Mount the backup directory
      - ./config.yaml:/backup/config.yaml  # Mount the configuration file
    networks:
      - web

networks:
  web:

Conclusion

Backing up multiple MySQL databases on Docker doesn’t have to be complicated. With Mysql-bkup, you can automate and streamline the process, ensuring your data is secure and easily recoverable. Whether you’re managing a single database or multiple, this tool provides the flexibility and reliability you need.

For more detailed instructions and advanced configurations, explore the official documentation: Mysql-bkup Documentation. Start automating your backups today and enjoy peace of mind knowing your data is protected.

Backing up your data is essential, especially when managing databases in Docker environments. Regular backups of your MySQL database can prevent data loss and ensure business continuity. This guide provides a comprehensive walkthrough on automating nightly backups for a MySQL database running inside a Docker container using the Mysql-bkup tool.

Mysql-bkup is a Docker container image designed to backup, restore, and migrate MySQL databases. It supports multiple storage options, including local storage, S3, SFTP, and Azure Blob, and ensures data security through GPG encryption.

Prerequisites

Before proceeding, ensure the following are in place:

• Docker installed and running.
• A MySQL or MariaDB database running in a Docker container.
• (Optional) S3-compatible storage, SFTP, or Azure Blob storage for remote backups.

Backup Methods

1. Backup Using Local Storage

This method binds local storage to the Docker container for database backups.

Method 1: Using Docker CLI

docker run --rm --network your_network_name \
  -v $PWD/backup:/backup/ \
  -e "DB_HOST=dbhost" \
  -e "DB_USERNAME=username" \
  -e "DB_PASSWORD=password" \
  -e "DB_PORT=3306" \
  jkaninda/mysql-bkup backup -d database_name

Explanation:

• The command runs a new Docker container on the same network as the MySQL database container.
• The backup is saved to a local directory (./backup) on the host machine.
• Ensure the mysql-bkup container is connected to the same Docker network as your database to avoid connectivity issues.

Method 2: Using Docker Compose

Create a compose.yaml file with the following content:

services:
  mysql-bkup:
    image: jkaninda/mysql-bkup
    container_name: mysql-bkup
    command: backup
    volumes:
      - ./backup:/backup
    environment:
      - DB_PORT=3306
      - DB_HOST=mysql
      - DB_NAME=database
      - DB_USERNAME=username
      - DB_PASSWORD=password
    networks:
      - web

networks:
  web:

Explanation:

• The mysql-bkup container is configured to back up the specified database.
• The backup is stored in the ./backup directory on the host machine.

Method 3: Recurring Backups

Mysql-bkup supports scheduled backups using cron expressions. You can use predefined schedules or custom intervals.

Predefined Schedules:

Example: Recurring Backup with Docker Compose

services:
  mysql-bkup:
    image: jkaninda/mysql-bkup
    container_name: mysql-bkup
    command: backup -d database -e @midnight
    volumes:
      - ./backup:/backup
    environment:
      - DB_PORT=3306
      - DB_HOST=mysql
      - DB_NAME=database
      - DB_USERNAME=username
      - DB_PASSWORD=password
    networks:
      - web

networks:
  web:

Explanation:

• The -e @midnight flag schedules a daily backup at midnight.
• Backups are stored in the ./backup directory.

2. Backup Using S3 Storage

Mysql-bkup supports S3-compatible storage for backups. Use the --storage s3 flag to enable this feature.

Example: S3 Backup with Docker Compose

services:
  mysql-bkup:
    image: jkaninda/mysql-bkup
    container_name: mysql-bkup
    command: backup --storage s3 -d database --cron-expression "0 1 * * *"
    environment:
      - DB_PORT=3306
      - DB_HOST=mysql
      - DB_NAME=database
      - DB_USERNAME=username
      - DB_PASSWORD=password
      ## AWS Configuration
      - AWS_S3_ENDPOINT=https://s3.amazonaws.com
      - AWS_S3_BUCKET_NAME=backup
      - AWS_REGION=us-west-2
      - AWS_ACCESS_KEY=xxxx
      - AWS_SECRET_KEY=xxxxx
      - AWS_DISABLE_SSL="false"
      - AWS_FORCE_PATH_STYLE=false
    networks:
      - web

networks:
  web:

Required Environment Variables:

• AWS_S3_ENDPOINT: S3 endpoint URL (e.g., https://s3.amazonaws.com).
• AWS_S3_BUCKET_NAME: Name of the S3 bucket.
• AWS_REGION: AWS region (e.g., us-west-2).
• AWS_ACCESS_KEY: AWS access key.
• AWS_SECRET_KEY: AWS secret key.
• AWS_DISABLE_SSL: Set to "true" for S3 alternatives without SSL.
• AWS_FORCE_PATH_STYLE: Set to "true" for S3 alternatives like Minio.

3. Backup Using Azure Blob Storage

Mysql-bkup also supports Azure Blob storage. Use the --storage azure flag to enable this feature.

Example: Azure Blob Backup with Docker Compose

services:
  mysql-bkup:
    image: jkaninda/mysql-bkup
    container_name: mysql-bkup
    command: backup --storage azure -d database --path your-custom-path
    environment:
      - DB_PORT=3306
      - DB_HOST=mysql
      - DB_NAME=database
      - DB_USERNAME=username
      - DB_PASSWORD=password
      ## Azure Blob Configuration
      - AZURE_STORAGE_CONTAINER_NAME=backup-container
      - AZURE_STORAGE_ACCOUNT_NAME=account-name
      - AZURE_STORAGE_ACCOUNT_KEY=your-account-key
    networks:
      - web

networks:
  web:

Required Environment Variables:

• AZURE_STORAGE_CONTAINER_NAME: Name of the Azure Blob container.
• AZURE_STORAGE_ACCOUNT_NAME: Azure Storage account name.
• AZURE_STORAGE_ACCOUNT_KEY: Azure Storage account key.

Notifications

Mysql-bkup can send email or Telegram notifications for backup success or failure.

Email Notifications

Configure SMTP credentials to enable email notifications.

Example: Email Notification Configuration

services:
  mysql-bkup:
    image: jkaninda/mysql-bkup
    container_name: mysql-bkup
    command: backup
    volumes:
      - ./backup:/backup
    environment:
      - DB_PORT=3306
      - DB_HOST=mysql
      - DB_NAME=database
      - DB_USERNAME=username
      - DB_PASSWORD=password
      ## SMTP Configuration
      - MAIL_HOST=smtp.example.com
      - MAIL_PORT=587
      - MAIL_USERNAME=your-email@example.com
      - MAIL_PASSWORD=your-email-password
      - MAIL_FROM=Backup Jobs <backup@example.com>
      - MAIL_TO=me@example.com,team@example.com
      - MAIL_SKIP_TLS=false
      - TIME_FORMAT=2006-01-02 at 15:04:05
      - BACKUP_REFERENCE=database/Paris cluster
    networks:
      - web

networks:
  web:

Telegram Notifications

Provide your Telegram bot token and chat ID to enable Telegram notifications.

Example: Telegram Notification Configuration

services:
  mysql-bkup:
    image: jkaninda/mysql-bkup
    container_name: mysql-bkup
    command: backup
    volumes:
      - ./backup:/backup
    environment:
      - DB_PORT=3306
      - DB_HOST=mysql
      - DB_NAME=database
      - DB_USERNAME=username
      - DB_PASSWORD=password
      ## Telegram Configuration
      - TG_TOKEN=[BOT ID]:[BOT TOKEN]
      - TG_CHAT_ID=your-chat-id
      - TIME_FORMAT=2006-01-02 at 15:04:05
      - BACKUP_REFERENCE=database/Paris cluster
    networks:
      - web

networks:
  web:

Conclusion

Automating MySQL database backups in Docker using Mysql-bkup is a robust and efficient way to ensure your data is secure and recoverable. With support for multiple storage options local, S3, SFTP, and Azure Blob this tool provides unparalleled flexibility. The added layer of GPG encryption ensures your backups remain secure, while customizable notifications keep you informed about backup successes or failures. By implementing these strategies, you can safeguard your critical data and minimize downtime in case of unexpected failures.

For more detailed instructions and advanced configurations, explore the official documentation: Mysql-bkup Documentation. Start automating your backups today and enjoy peace of mind knowing your data is protected.