README
¶
olareg
olareg (pronounced oh-la-reg) is a minimal OCI conformant container registry. It is designed around the OCI Layout structure for storing images in a directory. The minimal nature includes avoiding external dependencies, making the project easy to embed in unit tests or deployed in an edge environment as a cache.
Running as a Container
With persistent storage:
docker run -p 5000:5000 \
-v "olareg-data:/home/appuser/registry" \
ghcr.io/olareg/olareg serve --dir /home/appuser/registry
For an ephemeral registry:
docker run -p 5000:5000 --rm \
ghcr.io/olareg/olareg serve --store-type mem
Installing as a Binary
Binaries can be downloaded from the releases page.
Downloading the latest release for linux/amd64 can be done with curl:
curl -L https://github.com/olareg/olareg/releases/latest/download/olareg-linux-amd64 >olareg
chmod 755 olareg
For binaries downloaded on MacOS, the quarantine attribute can be removed with:
xattr -d com.apple.quarantine olareg
Using in Go Unit Tests
One of the goals of olareg was to serve as a simple registry implementation to test tooling that works with container registries. Integrating it into unit tests with the httptest based server involves the following setup:
func TestMethod(t *testing.T) {
rh := olareg.New(config.Config{
Storage: config.ConfigStorage{
StoreType: config.StoreMem,
RootDir: "./testdata", // serve content from testdata, writes only apply to memory
},
})
ts := httptest.NewServer(rh)
t.Cleanup(func() {
ts.Close()
_ = rh.Close()
})
tsURL, err := url.Parse(ts.URL)
if err != nil {
t.Fatal("failed to parse url %s: %v", ts.URL, err)
}
// send requests to tsURL.Host registry server ...
}
Verifying Signatures
Binaries and images have been signed with cosign.
For images:
cosign verify \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp https://github.com/olareg/olareg/.github/workflows/ \
ghcr.io/olareg/olareg:latest
For binaries:
curl -L https://github.com/olareg/olareg/releases/latest/download/olareg-linux-amd64 >olareg
chmod 755 olareg
curl -L https://github.com/olareg/olareg/releases/latest/download/olareg-linux-amd64.pem >olareg-linux-amd64.pem
curl -L https://github.com/olareg/olareg/releases/latest/download/olareg-linux-amd64.sig >olareg-linux-amd64.sig
cosign verify-blob \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp https://github.com/olareg/olareg/.github/workflows/ \
--certificate olareg-linux-amd64.pem \
--signature olareg-linux-amd64.sig \
olareg
rm olareg-linux-amd64.pem olareg-linux-amd64.sig
Documentation
¶
Overview ¶
Package olareg is used for running a minimal OCI conformant container registry.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var (
LogTrace = slog.LevelDebug - 4
)
Functions ¶
This section is empty.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func New ¶
New returns a Server. Ensure the resource is cleaned up with either Server.Close or Server.Shutdown.
Example (Directory) ¶
package main
import (
"context"
"fmt"
"os"
"github.com/olareg/olareg"
"github.com/olareg/olareg/config"
)
func main() {
ctx := context.Background()
// create a server backed by a local directory, listening on port 5000
regHandler := olareg.New(config.Config{
HTTP: config.ConfigHTTP{
Addr: ":5000",
},
Storage: config.ConfigStorage{
StoreType: config.StoreDir,
RootDir: "/path/to/storage",
},
})
// run the server
err := regHandler.Run(ctx)
if err != nil {
fmt.Fprintf(os.Stderr, "startup failed: %v", err)
return
}
// use the server
// ...
// shutdown the server
err = regHandler.Shutdown(ctx)
if err != nil {
fmt.Fprintf(os.Stderr, "shutdown failed: %v", err)
return
}
}
Output:
Example (Mem) ¶
package main
import (
"context"
"fmt"
"os"
"github.com/olareg/olareg"
"github.com/olareg/olareg/config"
)
func main() {
ctx := context.Background()
// create a server backed by memory, listening on port 5000
regHandler := olareg.New(config.Config{
HTTP: config.ConfigHTTP{
Addr: ":5000",
},
Storage: config.ConfigStorage{
StoreType: config.StoreMem,
},
})
// run the server
err := regHandler.Run(ctx)
if err != nil {
fmt.Fprintf(os.Stderr, "startup failed: %v", err)
return
}
// use the server
// ...
// shutdown the server
err = regHandler.Shutdown(ctx)
if err != nil {
fmt.Fprintf(os.Stderr, "shutdown failed: %v", err)
return
}
}
Output:
Example (Test) ¶
package main
import (
"context"
"fmt"
"io"
"net/http"
"net/http/httptest"
"net/url"
"os"
"github.com/olareg/olareg"
"github.com/olareg/olareg/config"
)
func main() {
ctx := context.Background()
// create a new olareg handler backed by memory
regHandler := olareg.New(config.Config{
Storage: config.ConfigStorage{
StoreType: config.StoreMem,
},
})
// start the handler using httptest for unit tests
ts := httptest.NewServer(regHandler)
defer ts.Close()
defer regHandler.Close()
// ping the /v2/ endpoint
u, err := url.Parse(ts.URL)
if err != nil {
fmt.Fprintf(os.Stderr, "failed to parse url: %v", err)
return
}
u.Path = "/v2/"
req, err := http.NewRequestWithContext(ctx, "GET", u.String(), nil)
if err != nil {
fmt.Fprintf(os.Stderr, "failed to generate request: %v", err)
return
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
fmt.Fprintf(os.Stderr, "failed to send request: %v", err)
return
}
body, err := io.ReadAll(resp.Body)
if err != nil {
fmt.Fprintf(os.Stderr, "failed to read body: %v", err)
return
}
fmt.Printf("body: %s\n", string(body))
}
Output: body: {}
func (*Server) Run ¶
Run starts a listener and serves requests. It only returns after a call to Server.Shutdown.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
olareg
command
|
|
|
Package config contains data types for configuration of olareg.
|
Package config contains data types for configuration of olareg. |
|
internal
|
|
|
cache
Package cache is used to store values with limits.
|
Package cache is used to store values with limits. |
|
cobradoc
Package cobradoc is used to generate documentation from cobra commands.
|
Package cobradoc is used to generate documentation from cobra commands. |
|
copy
Package copy is used internally to recursively copy filesystem content.
|
Package copy is used internally to recursively copy filesystem content. |
|
godbg
Package godbg provides tooling for debugging Go
|
Package godbg provides tooling for debugging Go |
|
httplog
Package httplog provides a log/slog logging middleware for http servers.
|
Package httplog provides a log/slog logging middleware for http servers. |
|
sloghandle
Package sloghandle includes handlers for slog.
|
Package sloghandle includes handlers for slog. |
|
store
Package store is used to interface with different types of storage (memory, disk)
|
Package store is used to interface with different types of storage (memory, disk) |
|
template
Package template wraps a common set of templates around text/template
|
Package template wraps a common set of templates around text/template |
|
version
Package version returns details on the Go and Git repo used in the build
|
Package version returns details on the Go and Git repo used in the build |
|
Package types contains various data types and well known constants.
|
Package types contains various data types and well known constants. |
Click to show internal directories.
Click to hide internal directories.