README
¶
[⬇️ Download] [🚀 All Releases] [📚 Installation] [✏️ Contributing]
Finch Daemon
The Finch Daemon project is an open source container runtime engine that enables users to integrate software that uses Docker's RESTful APIs as a programmatic dependency. Some core features include:
- A partial implementation of the Docker API Spec v1.43 - see supported endpoints for details
- Native support for Linux environments
The Finch Daemon project is actively taking contributions, especially to improve API compatibility.
Onboarding & Development
Please review CONTRIBUTING.md for onboarding, as well as for an overview of the development cycle for this project. Additionally, check the Makefile for additional information on setup & configuration.
Quickstart
Make sure NerdCTL and Containerd are installed and set up
Linux
Getting started with Finch Daemon on Linux only requires a few steps:
- Clone the repository -
git clone https://github.com/runfinch/finch-daemon.git cd finch-daemon- Install Go and make sure that
go versionis >= 1.22 - Build and spin up the finch-daemon server with
make sudo bin/finch-daemon --debug --socket-owner $UID - Test any changes with
make test-unitandsudo make test-e2e
Experimental Features
Finch Daemon includes experimental features that can be enabled using the --experimental flag. These features are under development and may change in future releases.
Using Experimental Features
To enable experimental features, use the --experimental flag when starting the daemon:
sudo bin/finch-daemon --debug --socket-owner $UID --experimental
Current Experimental Features
OPA Authorization Middleware
The OPA (Open Policy Agent) middleware allows you to define authorization policies for API requests using Rego policy language. This feature requires both the --experimental flag and the --rego-file flag to be set.
Example usage:
sudo bin/finch-daemon --debug --socket-owner $UID --experimental --rego-file /path/to/policy.rego
For detailed documentation on the OPA middleware, see opa-middleware.md.
Creating a systemd service
If you want finch-daemon to be managed as a systemd service, for benefits like automatic restart if it gets killed, you can configure it as a systemd service on Linux by following these steps:
cd /path/to/finch-daemonsudo cp finch.service /etc/systemd/system/- Refresh the service files to include the new service -
sudo systemctl daemon-reload - Start the service -
sudo systemctl start finch.service - To check the status of the service -
sudo systemctl status finch.service - To enable the service on every reboot -
sudo systemctl enable finch.service - To disable the service on every reboot -
sudo systemctl disable finch.service
Reporting an issue
If you encounter anything that seems wrong, please check out our issues tab first — someone may have already encountered your problem! If it's there, please add to the existing issue thread.
If you can't find an existing issue, feel free to open a new one. As a remninder, anything related to security should NOT go through regular reporting channels. Please refer to Security for guidance on how to report such issues.
Legal
Brought to you courtesy of our legal counsel. For more context, please see the NOTICE document in this repo.
Use and transfer of Finch Daemon may be subject to certain restrictions by the United States and other governments.
It is your responsibility to ensure that your use and/or transfer does not violate applicable laws.
For more information, please see https://www.bis.doc.gov
Licensing
Finch Daemon is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api provides types and interfaces that can be used by client-side software to communicate with finch daemon.
|
Package api provides types and interfaces that can be used by client-side software to communicate with finch daemon. |
|
credential
Package credential contains functions and structures related to credential management APIs
|
Package credential contains functions and structures related to credential management APIs |
|
handlers/builder
Package builder comprises functions, interfaces and structures related to build APIs
|
Package builder comprises functions, interfaces and structures related to build APIs |
|
handlers/container
Package container comprises functions and structures related to container APIs
|
Package container comprises functions and structures related to container APIs |
|
handlers/system
Package system contains functions and structures related to system level APIs
|
Package system contains functions and structures related to system level APIs |
|
handlers/volume
package volume defines the API service and handlers for the volumes API.
|
package volume defines the API service and handlers for the volumes API. |
|
cmd
|
|
|
finch-credential-helper
command
Package main implements a credential helper for Finch daemon
|
Package main implements a credential helper for Finch daemon |
|
finch-daemon
command
|
|
|
e2e
|
|
|
client
Package client provides a client for communicating with finch-daemon using unix sockets.
|
Package client provides a client for communicating with finch-daemon using unix sockets. |
|
tests
Package tests contains the exported functions that are meant to be imported as test cases.
|
Package tests contains the exported functions that are meant to be imported as test cases. |
|
util
Package testutil holds code that may be useful for any of the e2e subpackages (including e2e itself).
|
Package testutil holds code that may be useful for any of the e2e subpackages (including e2e itself). |
|
internal
|
|
|
service/builder
Package builder consists of definition of service structures and methods related to build APIs
|
Package builder consists of definition of service structures and methods related to build APIs |
|
service/container
Package container comprises functions and structures related to container APIs
|
Package container comprises functions and structures related to container APIs |
|
service/volume
package volume defines the volumes service.
|
package volume defines the volumes service. |
|
mocks
|
|
|
mocks_archive
Package mocks_archive is a generated GoMock package.
|
Package mocks_archive is a generated GoMock package. |
|
mocks_backend
Package mocks_backend is a generated GoMock package.
|
Package mocks_backend is a generated GoMock package. |
|
mocks_builder
Package mocks_builder is a generated GoMock package.
|
Package mocks_builder is a generated GoMock package. |
|
mocks_cio
Package mocks_cio is a generated GoMock package.
|
Package mocks_cio is a generated GoMock package. |
|
mocks_container
Package mocks_container is a generated GoMock package.
|
Package mocks_container is a generated GoMock package. |
|
mocks_credential
Package mocks_credential is a generated GoMock package.
|
Package mocks_credential is a generated GoMock package. |
|
mocks_distribution
Package mocks_distribution is a generated GoMock package.
|
Package mocks_distribution is a generated GoMock package. |
|
mocks_ecc
Package mocks_ecc is a generated GoMock package.
|
Package mocks_ecc is a generated GoMock package. |
|
mocks_exec
Package mocks_exec is a generated GoMock package.
|
Package mocks_exec is a generated GoMock package. |
|
mocks_http
Package mocks_http is a generated GoMock package.
|
Package mocks_http is a generated GoMock package. |
|
mocks_image
Package mocks_image is a generated GoMock package.
|
Package mocks_image is a generated GoMock package. |
|
mocks_logger
Package mocks_logger is a generated GoMock package.
|
Package mocks_logger is a generated GoMock package. |
|
mocks_network
Package mocks_network is a generated GoMock package.
|
Package mocks_network is a generated GoMock package. |
|
mocks_remotes
Package mocks_remotes is a generated GoMock package.
|
Package mocks_remotes is a generated GoMock package. |
|
mocks_statsutil
Package mocks_statsutil is a generated GoMock package.
|
Package mocks_statsutil is a generated GoMock package. |
|
mocks_system
Package mocks_system is a generated GoMock package.
|
Package mocks_system is a generated GoMock package. |
|
mocks_volume
Package mocks_volume is a generated GoMock package.
|
Package mocks_volume is a generated GoMock package. |
|
pkg
|
|
|
config
Package config provides shared configuration used throughout the application
|
Package config provides shared configuration used throughout the application |
|
credential
Package credential consists of definition of service structures and methods related to credential management
|
Package credential consists of definition of service structures and methods related to credential management |
|
errdefs
Package errdefs contains the error definitions (i.e., domain types).
|
Package errdefs contains the error definitions (i.e., domain types). |
|
flog
Package flog contains logging-related APIs.
|
Package flog contains logging-related APIs. |
|
Package version provides the global default latest API server version for the project
|
Package version provides the global default latest API server version for the project |