diff --git a/README.md b/README.md index c85704a..ee226e5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,9 @@ -# finch-daemon +[[⬇️ **Download]**](https://github.com/runfinch/finch-daemon/releases) +[[🚀 **All Releases]**](https://github.com/runfinch/finch-daemon/releases) +[[📚 **Installation]**](#quickstart) +[[✏️ **Contributing]**](CONTRIBUTING.md) + +# Finch Daemon The Finch Daemon project is a container runtime engine that enables users to seamlessly integrate their software which has programmatic dependencies on Docker RESTful APIs. This project currently implements the [Docker API Spec v1.43](https://docs.docker.com/engine/api/v1.43/). @@ -7,54 +12,70 @@ The Finch Daemon project is a container runtime engine that enables users to sea Please review [CONTRIBUTING.md](./CONTRIBUTING.md) for onboarding as well for an overview of the development cycle for this project. Additionally, check the [Makefile](./Makefile) for additional information on setup & configuration. ## Quickstart +Make sure [NerdCTL](https://github.com/containerd/nerdctl) and [Containerd](https://github.com/containerd/containerd) are installed and set up -### macOS -Note that with macOS, it is not possible to run unit tests with `make run-unit-tests` or do code-gen with `make code-gen` directly as this is a Linux project. It is possible, however, to build the project on macOS with `make` and run the linux-related commands in the finch vm. +### Linux +Getting started with Finch Daemon on Linux only requires a few steps: -1. Get finch, `brew install finch` -2. Add the unix socket forwarding to `/Applications/Finch/lima/data/finch/lima.yaml`: - ```yaml - portForwards: - - guestSocket: "/run/finch.sock" - hostSocket: "{{.Dir}}/sock/finch.sock" - ``` -3. Init the vm to apply the changes (or restart if Finch was already running): - ```bash - # init - finch vm init - - # restart - finch vm stop - finch vm start - ``` -4. Pull finch-daemon from the GitHub repo to somewhere under your home directory: `git clone https://github.com/runfinch/finch-daemon.git` -5. Check if you have go installed with `go version`, if not, install go with `brew install go` -6. Build finch-daemon with `make` -7. Spin up the finch-daemon server in finch's vm: - ```bash - LIMA_HOME=/Applications/Finch/lima/data /Applications/Finch/lima/bin/limactl shell finch - cd +1. Clone the Github repository - `git clone https://github.com/runfinch/finch-daemon.git` +2. `cd finch-daemon` +3. Install Go and make sure that `go version` is >= 1.22 +4. Build and spin up the finch-daemon server with + ```bash + make sudo bin/finch-daemon --debug --socket-owner $UID ``` -8. Test the project and use finch to confirm changes - - Using curl: - ```bash - curl -v -X GET --unix-socket /Applications/Finch/lima/data/finch/sock/finch.sock 'http://localhost/version' - ``` - - Using Docker CLI: - ```bash - DOCKER_HOST=unix:///Applications/Finch/lima/data/finch/sock/finch.sock docker images - ``` - - Using the Docker python SDK (after installing python3): - ```bash - # Install docker python SDK - python3 -m pip install docker - # Start python - DOCKER_HOST=unix:///Applications/Finch/lima/data/finch/sock/finch.sock python3 - ``` - ```python - >>> import docker - >>> client = docker.from_env() - >>> con = client.containers.get("test-container") - >>> con.attach(stream=True, logs=True, demux=True) - ``` \ No newline at end of file +5. Test any changes with `make run-unit-tests` and `sudo make run-e2e-tests` + + +## Creating a systemd service +Sometimes, you may wish to have a script be controlled by systemd, or to have the script restart by itself when it gets killed. You can configure such a service using systemd on Linux by following these steps: + +1. `cd /path/to/finch-daemon` +2. Create a `finch.service` file, with the following contents: + ```ini + [Unit] + Description=finch daemon %I + Documentation=https://runfinch.com + After=network.target local-fs.target containerd.service + Wants=network.target containerd.service + + [Service] + ExecStart=/usr/local/bin/finch-daemon --debug --socket-owner %i + + Type=notify + Delegate=yes + Restart=always + RestartSec=5 + + [Install] + WantedBy=multi-user.target + ``` +3. Refresh the service files to include the new service - `sudo systemctl daemon-reload` +4. Start the service - `sudo systemctl start finch.service` +5. To check the status of the service - `sudo systemctl status finch.service` +6. To enable the service on every reboot - `sudo systemctl enable finch.service` +7. To disable the service on every reboot - `sudo systemctl disable finch.service` + +----- + + +Legal +===== + +*Brought to you courtesy of our legal counsel. For more context, +please see the [NOTICE](https://github.com/runfinch/finch-daemon/blob/main/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](https://github.com/runfinch/finch-daemon/blob/main/LICENSE) for the full +license text. \ No newline at end of file