https://github.com/lucas-labs/kurv
๐ค๐ฎ๐ซ๐ฏ โบ process manager to deamonize/run background processes
https://github.com/lucas-labs/kurv
collaborate daemon daemonize daemons lightweight node process-manager processes rust
Last synced: 3 months ago
JSON representation
๐ค๐ฎ๐ซ๐ฏ โบ process manager to deamonize/run background processes
- Host: GitHub
- URL: https://github.com/lucas-labs/kurv
- Owner: lucas-labs
- License: mit
- Created: 2023-12-09T00:10:52.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-02-11T11:18:11.000Z (4 months ago)
- Last Synced: 2025-02-27T14:32:24.351Z (3 months ago)
- Topics: collaborate, daemon, daemonize, daemons, lightweight, node, process-manager, processes, rust
- Language: Rust
- Homepage: https://kurv.lucode.dev
- Size: 225 KB
- Stars: 16
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
๐ค๐ฎ๐ซ๐ฏ is a process manager, mainly for Node.js and Python applications. It's written in Rust. It daemonizes your apps so that they can run in the background. It also restarts them if they crash.
> [!WARNING]
> Heads up, this project is my Rust-learning playground and not production-ready yet:
>
> - I built this because my apps needed a process manager, and I had an itch to learn Rust. So, here it is... my first Rust project!
> - No tests yet (oops!)
> - Tested only on Windows 11
> - Rust newbie alert! ๐จ
> - Using it for my own projects, but not on a grand scale
## Why ๐ค๐ฎ๐ซ๐ฏ?
So, why the name ๐ค๐ฎ๐ซ๐ฏ? Well, it means "basket" in many languages I don't speak, like Norwegian (but it sounded cool ๐). Think of ๐ค๐ฎ๐ซ๐ฏ as a basket for your apps. In kurv, we call each deployed app as an `egg`. So, let's go and collect some eggs ๐ฅ in your basket ๐งบ.
## Installation
> [!NOTE]
> ๐ค๐ฎ๐ซ๐ฏ can run either as a server or as a CLI client, using the same binary.
>
> The server is responsible for managing the eggs, while the client is used to interact with the server and tell it what to do or ask it for information.
### Download binaries
Download the latest release [from GitHub](https://github.com/lucas-labs/kurv/releases).
### crates.io
You can also install it from [crates.io](https://crates.io/crates/kurv) using `cargo`:
```bash
cargo install kurv
```
## Usage
### Start the server
To get the server rolling, type:
```bash
kurv server
```
> [!IMPORTANT]
> - ๐ค๐ฎ๐ซ๐ฏ will create a file called `.kurv` where it will store the current
> state of the server. The file will be created in the same directory where
> the binary is located or in the path specified by the `KURV_HOME_KEY`
> environment variable.
>
> - since ๐ค๐ฎ๐ซ๐ฏ can be used both as a server and as a client, if you want
> to run it as a server, you need to set the `KURV_SERVER` environment
> to `true`. This is just a safety measure to prevent you from running
> the server when you actually want to run the client.
> To bypass this, you can use the `--force` flag (`kurv server --force`)
### Collect some ๐ฅ
To deploy/start/daemonize an app (collect an egg), do:
```bash
kurv collect
```
The path should point to a YAML file that contains the configuration for the egg.
It should look something like this:
```yaml title="myegg.kurv"
name: fastapi # the name of the egg / should be unique
command: poetry # the command/program to run
args: # the arguments to pass to the command
- run
- serve
cwd: /home/user/my-fastapi-app # the working directory in which the command will be run
env: # the environment variables to pass to the command
FASTAPI_PORT: 8080
```
This will run the command `poetry run serve` in `/home/user/my-fastapi-app` with the environment variable `FASTAPI_PORT` set to `8080`.
If for some reason, the command/program crashes or exits, ๐ค๐ฎ๐ซ๐ฏ will revive it!
### Show me my eggs
If you want a summary of the current state of your eggs, run:
```zsh
$ kurv list
๐ฅ eggs snapshot
โญโโโโฌโโโโโโโโฌโโโโโโโโโโโโฌโโโโโโโโโโฌโโโโฌโโโโโโโโโฎ
โ # โ pid โ name โ status โ โบ โ uptime โ
โโโโโผโโโโโโโโผโโโโโโโโโโโโผโโโโโโโโโโผโโโโผโโโโโโโโโค
โ 1 โ 35824 โ fastapi โ running โ 0 โ 1s โ
โ 2 โ 0 โ fastapi-2 โ stopped โ 0 โ - โ
โฐโโโโดโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโดโโโโดโโโโโโโโโฏ
```
For details on a specific egg:
``` sh
$ kurv egg
```
This will show you the egg's configuration, process details, etc.
### Stop an egg
To halt an egg without removing it:
``` sh
$ kurv stop
```
This will stop the process but keep its configuration in the basket in case
you want to start it again later.
### Remove an egg
To actually remove an egg, run:
``` sh
$ kurv remove
```
It will stop the process and remove the egg from the basket.
### Restart
If you need the process to be restarted, run:
``` sh
$ kurv restart
```
### To do list
๐ค๐ฎ๐ซ๐ฏ is still under development. Here are some of the things I'm planning to add:
- [ ] Simple password protection
- [ ] Remotely manage eggs
- [ ] SSL support
- [ ] Handle cors correctly
And last but not least:
- [ ] Tests (I know, I know... ๐คญ)
#### Plugins / extensions
Since ๐ค๐ฎ๐ซ๐ฏ is a process manager, we can easily extend its functionality by adding
plugin eggs (simple eggs managed by ๐ค๐ฎ๐ซ๐ฏ itself that provide additional functionality).
Here are some ideas I have for plugins:
- [ ] Web UI
- [ ] Log Viewer
- [ ] Log Rotation
### Inspiration
#### pm2
Inspired by the robust process manager, [pm2](https://pm2.keymetrics.io/), my goal with ๐ค๐ฎ๐ซ๐ฏ was to create a lightweight alternative. Not that pm2 is a resource hog, but I found myself in a server with extremely limited resources. Plus, I was itching for an excuse to dive into Rust, and voila, ๐ค๐ฎ๐ซ๐ฏ was born.
#### eggsecutor
Derived from [eggsecutor](https://github.com/lucas-labs/kurv), ๐ค๐ฎ๐ซ๐ฏ adopted the whimsical term "eggs" to represent deployed applications.
#### pueue
Insights from [pueue](https://github.com/Nukesor/pueue) were instrumental in helping me understand how to manage processes in Rust.
-------
With ๐ง from Argentina ๐ฆ๐ท