https://github.com/peeklapp/peekl
The main repository for the Peekl project
https://github.com/peeklapp/peekl
configuration-management golang infrastructure-as-code linux
Last synced: about 1 month ago
JSON representation
The main repository for the Peekl project
- Host: GitHub
- URL: https://github.com/peeklapp/peekl
- Owner: peeklapp
- License: mit
- Created: 2026-02-10T20:13:32.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-28T15:28:48.000Z (3 months ago)
- Last Synced: 2026-03-28T17:49:10.366Z (3 months ago)
- Topics: configuration-management, golang, infrastructure-as-code, linux
- Language: Go
- Homepage: https://peekl.dev
- Size: 146 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Peekl
> [!CAUTION]
> This project is still under active development. Expect breaking changes at any time. Use on your servers at your own risk.
Peekl is a simple yet powerful configuration management tool ! It's a more modern and highly opinionated solution at how tools such as Ansible and Puppet works.
1. [Getting started](#getting-started)
1. [Installing the server](#installing-the-server)
2. [Installing the agent](#installing-the-agent)
2. [Documentation](#documentation)
3. [Contributing](#contributing)
4. [License](#license)
## Getting started
Peekl is composed of two main components :
- The agent, that you install on each node that you want to manage.
- The server, that the agent will communicate with to get their catalog.
### Installing the server
The first step you will have to follow is to install the server. For that you can download the latest version of Peekl on GitHub.
By default the certificate generated by the server during it's bootstrap will only contains `peekl` as the domain name.
If you want to use a custom domain name, such as `example.peekl.dev`, you should add a configuration file at path `/etc/peekl/config/server.yml` with the following content.
```yaml
certificates:
bootstrap_dns_names:
- 'example.peekl.dev'
```
Then you can proceed and start the installation
```bash
export PEEKL_VERSION=0.1.0
export PEEKL_ARCH=amd64
wget https://github.com/peeklapp/peekl/releases/download/${PEEKL_VERSION}/peekl-server_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb
apt install ./peekl-server_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb
```
The server should automatically start, bootstrap himself, and be ready to receive queries.
You can validate that everything is working correctly using the following command.
```bash
systemctl status peekl-server.service
```
By default, and for security purpose, Peekl will only listen on host `127.0.0.1` and port `9040`.
You can change this behavior by adding the following configuration to the configuration file.
```yaml
listen:
host: 0.0.0.0
port: 9040
```
### Installing the agent
By default the agent will try to contact the Peekl server using `https://peekl:9040`
To work with this, you have two solutions :
Either make use of the `peekl` DNS name by adding it to the `/etc/hosts` file, using the command `echo '192.168.121.10 peekl' >> /etc/hosts` (update the IP accordingly to your case).
Or create a configuration file at path `/etc/peekl/config/agent.yml` and add the following content to it :
```yaml
server:
host: 192.168.121.10
port: 9040
```
In this case, also remember to update the IP address according to your situation.
Once this is done, you can proceed by just installing the agent using the Debian packages
```bash
export PEEKL_VERSION=0.1.0
export PEEKL_ARCH=amd64
wget https://github.com/peeklapp/peekl/releases/download/${PEEKL_VERSION}/peekl-agent_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb
apt install ./peekl-agent_${PEEKL_VERSION}_linux_${PEEKL_ARCH}.deb
```
The agent should be up and running at this point.
```bash
systemctl status peekl-agent.service
```
But you will still have to sign the certificate on the server side
Start by listing the pending certificates, your agent should be there
```bash
peekl-server ca list pending
```
And use the found name to sign the certificate
```bash
peekl-server ca sign --certname name_of_the_node
```
After a little bit of time the agent should download it's certificate. You can go faster by running it by hand
```bash
peekl-agent run
```
# Documentation
You find extensive documentation on the dedicated documentation website : [docs.peekl.dev](https://docs.peekl.dev)
# Contributing
Contributions are more than welcome. But please note that supporting every little use-case is not something feasible. In order to keep the project into a maintainable state, we might refuse improvements or features suggestions, if they're deemed incompatible with the ideas of what Peekl should be : simple and efficient.
Asking for help is always ok, and reporting bug even more.
# License
This software is distributed with the [MIT License](https://opensource.org/license/mit)