https://github.com/nickheyer/distroface
Container freedom with artifacts*
https://github.com/nickheyer/distroface
artifacts containers docker free golang svelte
Last synced: 8 months ago
JSON representation
Container freedom with artifacts*
- Host: GitHub
- URL: https://github.com/nickheyer/distroface
- Owner: nickheyer
- License: mit
- Created: 2025-01-30T04:24:26.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-02-20T02:13:49.000Z (8 months ago)
- Last Synced: 2025-02-20T03:23:43.478Z (8 months ago)
- Topics: artifacts, containers, docker, free, golang, svelte
- Language: Go
- Homepage:
- Size: 577 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
A container registry built for developers. Convenient and without compromise.
# DistroFace Docs
## Features
- Built-in Authentication & Authorization
- Modern Web UI
- Image Migration Tool
- Role-Based Access Control
- Tag Management
- Registry Statistics
## API Endpoints
### Authentication
| Endpoint | Method | Description | Required Role |
|----------|---------|-------------|---------------|
| `/auth/token` | GET/POST | Get registry authentication token | None |
| `/api/v1/auth/login` | POST | Web UI login | None |
| `/api/v1/auth/refresh` | POST | Refresh authentication token | None |
### Registry Operations
| Endpoint | Method | Description | Required Role |
|----------|---------|-------------|---------------|
| `/v2/_catalog` | GET | List repositories | VIEW:IMAGE |
| `/v2/{name}/tags/list` | GET | List tags | VIEW:TAG |
| `/v2/{name}/manifests/{reference}` | GET | Get manifest | PULL:IMAGE |
| `/v2/{name}/manifests/{reference}` | PUT | Upload manifest | PUSH:IMAGE |
| `/v2/{name}/blobs/{digest}` | GET | Download blob | PULL:IMAGE |
| `/v2/{name}/blobs/uploads/` | POST | Start blob upload | PUSH:IMAGE |
| `/v2/{name}/blobs/uploads/{uuid}` | PATCH | Upload blob chunk | PUSH:IMAGE |
| `/v2/{name}/blobs/uploads/{uuid}` | PUT | Complete blob upload | PUSH:IMAGE |
### Group & Role Management
| Endpoint | Method | Description | Required Role |
|----------|---------|-------------|---------------|
| `/api/v1/groups` | GET | List groups | VIEW:GROUP |
| `/api/v1/groups/{name}` | PUT | Update group | UPDATE:GROUP |
| `/api/v1/groups/{name}` | DELETE | Delete group | DELETE:GROUP |
| `/api/v1/roles` | GET | List roles | VIEW:SYSTEM |
| `/api/v1/roles/{name}` | PUT | Update role | ADMIN:SYSTEM |
| `/api/v1/roles/{name}` | DELETE | Delete role | ADMIN:SYSTEM |
### Artifact Management
| Endpoint | Method | Description | Required Role |
|----------|---------|-------------|---------------|
| `/api/v1/artifacts/repos` | GET | List artifact repositories | VIEW:REPO |
| `/api/v1/artifacts/repos` | POST | Create artifact repository | CREATE:REPO |
| `/api/v1/artifacts/repos/{repo}` | DELETE | Delete repository | DELETE:REPO |
| `/api/v1/artifacts/{repo}/upload` | POST | Initialize artifact upload | UPLOAD:ARTIFACT |
| `/api/v1/artifacts/{repo}/upload/{uuid}` | PATCH | Upload artifact chunk | UPLOAD:ARTIFACT |
| `/api/v1/artifacts/{repo}/upload/{uuid}` | PUT | Complete artifact upload | UPLOAD:ARTIFACT |
| `/api/v1/artifacts/{repo}/{version}/{path}` | GET | Download artifact | DOWNLOAD:ARTIFACT |
| `/api/v1/artifacts/{repo}/{version}/{path}` | DELETE | Delete artifact | DELETE:ARTIFACT |
| `/api/v1/artifacts/{repo}/versions` | GET | List artifact versions | VIEW:ARTIFACT |
| `/api/v1/artifacts/search` | GET | Search artifacts | VIEW:ARTIFACT |
### Settings Management
| Endpoint | Method | Description | Required Role |
|----------|---------|-------------|---------------|
| `/api/v1/settings/{section}` | GET | Get settings | ADMIN:SYSTEM |
| `/api/v1/settings/{section}` | PUT | Update settings | ADMIN:SYSTEM |
| `/api/v1/settings/{section}/reset` | POST | Reset settings | ADMIN:SYSTEM |
### User Management
| Endpoint | Method | Description | Required Role |
|----------|---------|-------------|---------------|
| `/api/v1/users` | GET | List users | VIEW:USER |
| `/api/v1/users` | POST | Create user | CREATE:USER |
| `/api/v1/users/groups` | PUT | Update user groups | UPDATE:USER |
### Migration
| Endpoint | Method | Description | Required Role |
|----------|---------|-------------|---------------|
| `/api/v1/registry/migrate` | POST | Start migration | MIGRATE:TASK |
| `/api/v1/registry/migrate/status` | GET | Check migration status | MIGRATE:TASK |
## DFCli - API Client Tool
`dfcli` is a command-line interface for interacting with DistroFace. It provides commands for managing images, artifacts, users, groups, roles, and settings.
### Get the cli
The `dfcli` binary can be obtained from the releases tab (if one exist) or can be built by cloning this repo and running `make build-cli` in the project root.
### Authentication
```bash
# Login to server
dfcli login
dfcli login -u username -p password
# Logout
dfcli logout
```
### Image Management
```bash
# List images
dfcli image list
# Manage image tags
dfcli image tags
dfcli image delete
# Update visibility
dfcli image visibility
```
### Artifact Management
```bash
# Create/list repositories
dfcli artifact create [-d description] [-p]
dfcli artifact list
# Upload artifacts
dfcli artifact upload [-v version] [-p path] [--property key=value]
# Download artifacts (using query route)
# - By default, if exactly one artifact matches, returns that file
# - If multiple match, returns ZIP or TAR.GZ (or force archive with --archive)
dfcli artifact download \
--version 1.2.3 \
--path bin/cli-binary \
--property env=production \
--archive \
--format tar.gz \
--output downloaded.tar.gz
# Or with shorter flags:
dfcli artifact download my-repo -v 1.2.3 -p bin/cli-binary -P env=prod,branch=main --archive --format zip -o out.zip
# Delete artifacts (legacy direct path)
dfcli artifact delete
# Search artifacts
dfcli artifact search [--property key=value]
```
### User Management
```bash
# List and manage users
dfcli user list
dfcli user create -p [-g group1,group2]
dfcli user delete
dfcli user groups -g
```
### Group Management
```bash
# List and manage groups
dfcli group list
dfcli group create -d -r
dfcli group update [-d description] [-r role1,role2]
dfcli group delete
```
### Role Management
```bash
# List and manage roles
dfcli role list
dfcli role update [--add ACTION:RESOURCE] [--remove ACTION:RESOURCE]
dfcli role delete
```
### Settings Management
```bash
# View and manage settings
dfcli settings get
dfcli settings update -s key=value
dfcli settings reset
```
### Configuration
The CLI configuration is stored in `~/.dfcli/config.json`. You can specify a different server URL using the `--server` flag or by setting it in the config file:
```bash
dfcli --server http://registry.example.com
```
> [!note]
> `registry.example.com` would also work, assuming http not https.
## Authentication Model
![]()
Distroface runs the webui user auth and permissions model through the same channels as the docker client.
## Quick Start
```bash
# Run with Docker
docker run -p 8668:8668 \
-v /path/to/data:/data \
nickheyer/distroface:latest
# Default login
Username: admin
Password: admin
```
## Development
```bash
# Install dependencies
make deps
# Build + run in development mode
make dev
# Build for production
make build
# Build the cli tool
make build-cli
```
## License
MIT License - see [LICENSE](LICENSE) for details