epoch

command module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 1, 2026 License: MIT Imports: 6 Imported by: 0

README

epoch

Snapshot registry for Cocoon MicroVMs. Stores versioned manifests and content-addressed blobs in any S3-compatible object store, exposes an OCI-style /v2/ API, and ships a small web UI for browsing repositories and managing access tokens.

Overview

  • Content-addressed storage -- blobs are de-duplicated by SHA-256 digest
  • OCI Distribution API -- /v2/ push and pull, compatible with standard registry tooling
  • MySQL metadata index -- queryable catalog for the web UI and control API
  • SSO login -- optional Google OAuth or generic OIDC for the web UI
  • Token management -- create and revoke bearer tokens from the dashboard
  • vk-cocoon integration -- registry.NewPuller(...) pulls snapshots on demand before VM creation

Architecture

              vk-cocoon / epoch CLI
                       |
                 registry package
                 /             \
            S3 object store   Epoch HTTP server
                                /      |      \
                          /v2/ API   /api/   web UI
                                      |
                                    MySQL

Object layout in the bucket:

epoch/
  catalog.json
  manifests/<repo>/<tag>.json
  blobs/sha256/<digest>

Installation

Download

Download a pre-built binary from GitHub Releases:

# Linux (amd64)
curl -fSL -o epoch https://github.com/cocoonstack/epoch/releases/latest/download/epoch-linux-amd64
chmod +x epoch
sudo mv epoch /usr/local/bin/

# Linux (arm64)
curl -fSL -o epoch https://github.com/cocoonstack/epoch/releases/latest/download/epoch-linux-arm64
chmod +x epoch
sudo mv epoch /usr/local/bin/

# macOS (Apple Silicon)
curl -fSL -o epoch https://github.com/cocoonstack/epoch/releases/latest/download/epoch-darwin-arm64
chmod +x epoch
sudo mv epoch /usr/local/bin/
Build from source
git clone https://github.com/cocoonstack/epoch.git
cd epoch
make build          # produces ./epoch

Configuration

Object storage
Variable Description
EPOCH_S3_ENDPOINT S3 endpoint (with or without scheme)
EPOCH_S3_ACCESS_KEY Access key
EPOCH_S3_SECRET_KEY Secret key
EPOCH_S3_BUCKET Bucket name
EPOCH_S3_REGION Region (optional)
EPOCH_S3_SECURE true / false; inferred from scheme if omitted
EPOCH_S3_PREFIX Key prefix (default epoch/)
EPOCH_S3_ENV_FILE Env file path (default ~/.config/epoch/s3.env)
Authentication

Registry clients (/v2/):

  • Bearer token from EPOCH_REGISTRY_TOKEN or tokens created via the UI
  • Tokens are validated by SHA-256 hash against MySQL

Web UI / control API:

  • Disabled by default (open access)
  • Set SSO_PROVIDER=google or SSO_PROVIDER=oidc to enable session-based login
  • See deploy/epoch-server.yaml for the full list of SSO variables
Deployment files
Path Purpose
deploy/docker-compose.yaml Local MySQL + MinIO
deploy/epoch-server.yaml Kubernetes Deployment template
deploy/Dockerfile Container image build
deploy/epoch-server.service systemd unit file

Quick Start

Start local dependencies:

cd deploy
export MYSQL_ROOT_PASSWORD=changeme
export MYSQL_PASSWORD=changeme
export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=changeme
docker compose up -d

Build and run:

make build

export EPOCH_S3_ENDPOINT=http://127.0.0.1:9000
export EPOCH_S3_ACCESS_KEY=minioadmin
export EPOCH_S3_SECRET_KEY=changeme
export EPOCH_S3_BUCKET=epoch
export EPOCH_S3_SECURE=false

./epoch serve --addr :4300 --dsn 'epoch:epoch@tcp(127.0.0.1:3306)/epoch?parseTime=true'

Push and inspect a snapshot:

./epoch push ubuntu-dev --tag latest
./epoch ls
./epoch inspect ubuntu-dev:latest

Development

make build          # stripped binary
make test           # race-detected tests with coverage
make lint           # golangci-lint
make fmt            # gofumpt + goimports
make deps           # tidy modules
make all            # full pipeline
make help           # show all targets
Project Role
vk-cocoon Virtual kubelet provider managing VM lifecycle
cocoon-operator CocoonSet and Hibernation CRDs
cocoon-webhook Admission webhook for sticky scheduling
glance Web dashboard for VM access

License

MIT

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis
Package cocoon provides types and path helpers for Cocoon's snapshot storage.
 Package cocoon provides types and path helpers for Cocoon's snapshot storage.
internal
util
Package util provides shared helper functions used across epoch packages.
 Package util provides shared helper functions used across epoch packages.
Package manifest defines the Epoch registry data model.
 Package manifest defines the Epoch registry data model.
Package registry implements the Epoch snapshot registry backed by an S3-compatible object store.
 Package registry implements the Epoch snapshot registry backed by an S3-compatible object store.
OIDC authentication for the Epoch web UI and control plane API.
 OIDC authentication for the Epoch web UI and control plane API.
Package store provides MySQL-backed metadata storage for the Epoch control plane.
 Package store provides MySQL-backed metadata storage for the Epoch control plane.
Package ui embeds the frontend static files.
 Package ui embeds the frontend static files.
Package version holds build-time version metadata, injected via ldflags.
 Package version holds build-time version metadata, injected via ldflags.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.