01cloud-backup

01cloud-backup is a Go-based gRPC service for orchestrating Kubernetes backup and restore workflows with Velero. It exposes a programmatic API for creating, listing, preserving, restoring, and deleting backups, while also persisting metadata in PostgreSQL and sending live status updates over WebSocket.

This project is a good fit if you want to build a platform, internal tool, or control plane that needs backup automation without wiring directly into Velero commands by hand.

Why This Project

• gRPC-first API for backup workflows
• Velero-backed backup and restore orchestration
• PostgreSQL-backed metadata persistence
• WebSocket notifications for status streaming
• Label and settings support for repeatable workflows
• Container-friendly development and build flow

Table of Contents

• Overview
• How It Works
• Features
• Tech Stack
• Prerequisites
• Quick Start
• Configuration
• Usage
• API Surface
• Project Layout
• Development
• Docker
• Contributing
• Security
• License

Overview

The service sits between your clients and your cluster backup system:

• clients call a gRPC API
• the service translates those calls into Velero operations
• backup metadata and restore-related state are stored in PostgreSQL
• status updates can be pushed to connected consumers through WebSocket

That makes 01cloud-backup useful as a backend component for dashboards, control planes, automation pipelines, or multi-tenant platform tooling.

How It Works

gRPC client
    |
    v
01cloud-backup
    |
    +--> Velero / Kubernetes resources
    +--> PostgreSQL metadata storage
    +--> WebSocket status broadcast

High-level request flow:

1. A client sends a backup or restore request over gRPC.
2. The service validates the request and invokes the corresponding backup logic.
3. Velero resources are created or queried inside the target cluster.
4. Backup metadata, labels, and settings are stored in PostgreSQL.
5. Status can be published to downstream consumers through WebSocket.

Features

Backup lifecycle

• Create a backup for a namespace or workload scope
• List existing backups with pagination support
• Fetch backup details for a specific backup
• Preserve important backups from cleanup workflows
• Restore from an existing backup
• Delete backups and associated metadata

Settings and labels

• Save backup settings for reuse
• Retrieve saved backup settings by namespace
• Attach labels to backups for filtering and organization

Restore support

• Track environment-related metadata to improve restore fidelity
• Support restore listing workflows through the gRPC API

Realtime events

• Push status information through WebSocket connections

Tech Stack

• Go 1.20+
• gRPC / Protocol Buffers
• Velero
• Kubernetes client libraries
• PostgreSQL
• Docker

Prerequisites

Before running the service, make sure you have:

Requirement	Notes
Go	1.20 or later
Docker	Recommended for repeatable local builds
Kubernetes cluster	Required for real Velero-backed workflows
Velero	Installed and configured in the target cluster
PostgreSQL	Required for metadata persistence

If Velero is not installed yet, start with the official Velero installation guide.

Quick Start

1. Clone the repository

git clone https://github.com/berrybytes/01cloud-backup.git
cd 01cloud-backup

2. Create your local environment file

cp .env.sample .env

3. Fill in configuration values

At minimum, review:

• GRPC_SERVER_PORT
• DB_HOST
• DB_PORT
• DB_USER
• DB_PASSWORD
• DB_NAME
• DB_BACKUP_PATH
• WS_SERVER
• API_URL
• API_SECRET

4. Download dependencies

go mod download

5. Run the service

make run-dev

The server listens on the address configured by GRPC_SERVER_PORT.

Configuration

The application uses environment variables loaded from .env.

Example bootstrap:

cp .env.sample .env

Current environment keys from .env.sample:

Core service

Variable	Required	Description
DEBUG	No	Enables debug logging when set to true
GRPC_SERVER_PORT	Yes	Bind address for the gRPC server

Cloud and platform

Variable	Required	Description
GCLOUD_PROJECT	No	GCP project identifier when applicable
GCLOUD_NAMESPACE	No	Namespace or related cloud scoping value
WS_SERVER	Yes	WebSocket destination for status updates
API_URL	Yes	Upstream API endpoint
API_SECRET	Yes	Authentication token or secret for upstream API calls

Database

Variable	Required	Description
DB_HOST	Yes	PostgreSQL host
DB_PORT	Yes	PostgreSQL port
DB_USER	Yes	PostgreSQL username
DB_PASSWORD	Yes	PostgreSQL password
DB_NAME	Yes	PostgreSQL database name
DB_BACKUP_PATH	Yes	Filesystem path used for backup-related local storage

Security notes:

• .env should stay uncommitted
• use secret managers in production
• avoid pasting real credentials into issues or pull requests

Usage

Run locally

make run-dev

Run tests

make test-dev

Run linting

make lint

Format Go code

make format

Show available Make targets

make help

API Surface

Protocol buffer definitions live in pkg/proto/backup/backup.proto.

The primary gRPC service is Backup, with these RPCs:

RPC	Purpose
CreateBackup	Start a backup
ListBackup	List backups
DetailBackup	Get backup details
PreserveBackup	Mark or unmark a backup as preserved
RestoreBackup	Trigger a restore
RestoreListBackup	List restorable backups
DeleteBackup	Delete a backup
GetSettingBackup	Get saved backup settings
SaveSettingBackup	Save backup settings
AddLabelBackup	Add labels to a backup

If you need to regenerate protobuf artifacts, use the Make target that exists in this repo:

make grpc-compile

Project Layout

This README now reflects the actual repository layout:

01cloud-backup/
├── cmd/server/main.go
├── internal/backup/
├── internal/common/
├── internal/helper/
├── internal/model/
├── internal/repository/
├── internal/velero/
├── pkg/proto/backup/
├── .env.sample
├── Dockerfile
├── Makefile
└── README.md

Directory guide:

• cmd/server contains the application entrypoint
• internal/backup contains gRPC server and backup workflow logic
• internal/velero contains Velero integration code
• internal/repository contains persistence-related code
• internal/model contains domain and database models
• internal/helper contains shared helpers and utility code
• pkg/proto/backup contains protobuf definitions and generated Go stubs

Development

Local workflow

make format
make test-dev
make lint

Notes for contributors

• the service loads configuration from .env
• the current entrypoint is cmd/server/main.go
• some Make targets use Docker-based flows
• cluster-dependent features require a working Kubernetes + Velero setup

Suggested contributor improvements

Open source contributors can add value quickly by helping with:

• test coverage for backup and restore flows
• README examples and API usage snippets
• stronger local development docs
• CI hardening and release automation
• validation and error handling improvements

Docker

Build the image locally:

docker build -t 01cloud-backup:latest .

Run the container:

docker run --env-file .env -p 50051:50051 01cloud-backup:latest

Documentation

• ABOUT.md — Project mission, architecture, and why it exists
• RELEASES.md — Release process, versioning, and publishing procedures
• CHANGELOG.md — Version history and notable changes
• CONTRIBUTING.md — How to contribute code and improvements
• CODE_OF_CONDUCT.md — Community guidelines and expectations
• SECURITY.md — Security policy and vulnerability reporting

Contributing

Contributions are welcome.

Before opening a pull request, please review:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md

Helpful things to include in issues:

• your Go version
• Kubernetes version
• Velero version
• steps to reproduce
• relevant logs or error output
• configuration details with secrets removed

Security

If you discover a security issue, please follow the guidance in SECURITY.md.

License

Licensed under the Apache License 2.0.