Skip to content

Commit

Permalink
docs: ๐Ÿ“ update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
lucas-labs committed Jan 4, 2024
1 parent b89f74a commit 6e0dafb
Showing 1 changed file with 38 additions and 21 deletions.
59 changes: 38 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@
<br>
<br>

<p align="center">${\normalsize \textbf{kurv}}$ is a process manager, mainly for Node.js and Python applications. It's written in <code>Rust</code>. It daemonizes your apps so that they can run in the background. It also restarts them if they crash.</p>
<p align="center">๐ค๐ฎ๐ซ๐ฏ is a process manager, mainly for Node.js and Python applications. It's written in <code>Rust</code>. It daemonizes your apps so that they can run in the background. It also restarts them if they crash.
</p>

<p align="center"><img align="center" alt="Crates.io Version" src="https://img.shields.io/crates/v/kurv?style=flat-square&color=%2318181b&link=https%3A%2F%2Fcrates.io%2Fcrates%2Fkurv"></p>

<br>
<br>
Expand All @@ -20,24 +23,38 @@
> - Using it for my own projects, but not on a grand scale

## Why ${\normalsize \textbf{kurv}}$?
## Why ๐ค๐ฎ๐ซ๐ฏ?

So, why the name ${\normalsize \textbf{kurv}}$? Well, it means "basket" in many languages I don't speak, like Norwegian (but it sounded cool ๐Ÿ˜„). Think of ${\normalsize \textbf{kurv}}$ 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

Download the latest release from GitHub.
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]
> ${\normalsize \textbf{kurv}}$ can run either as a server or as a CLI client, using the same binary.
> ๐ค๐ฎ๐ซ๐ฏ 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

![kurv usage](.github/kurv.gif)


## Start the server
### Start the server

To get the server rolling, type:

Expand All @@ -46,18 +63,18 @@ kurv server
```

> [!IMPORTANT]
> - ${\normalsize \textbf{kurv}}$ will create a file called `.kurv` where it will store the current
> - ๐ค๐ฎ๐ซ๐ฏ 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 ${\normalsize \textbf{kurv}}$ can be used both as a server and as a client, if you want
> - 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 ๐Ÿฅš
### Collect some ๐Ÿฅš
To deploy/start/daemonize an app (collect an egg), do:

```bash
Expand All @@ -81,9 +98,9 @@ env: # the environment variables to pass to the command
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, ${\normalsize \textbf{kurv}}$ will revive it!
If for some reason, the command/program crashes or exits, ๐ค๐ฎ๐ซ๐ฏ will revive it!

## Show me my eggs
### Show me my eggs

If you want a summary of the current state of your eggs, run:

Expand All @@ -108,7 +125,7 @@ $ kurv egg <egg:name|id|pid>

This will show you the egg's configuration, process details, etc.

## Stop an egg
### Stop an egg

To halt an egg without removing it:

Expand All @@ -119,7 +136,7 @@ $ kurv stop <egg:name|id|pid>
This will stop the process but keep its configuration in the basket in case
you want to start it again later.

## Remove an egg
### Remove an egg

To actually remove an egg, run:

Expand All @@ -129,23 +146,23 @@ $ kurv remove <egg:name|id|pid>

It will stop the process and remove the egg from the basket.

## Restart
### Restart

If you need the process to be restarted, run:

``` sh
$ kurv restart <egg:name|id|pid>
```

## Inspiration
### Inspiration

### pm2
Inspired by the robust process manager, [pm2](https://pm2.keymetrics.io/), my goal with ${\normalsize \textbf{kurv}}$ 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, ${\normalsize \textbf{kurv}}$ was born.
#### 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), ${\normalsize \textbf{kurv}}$ adopted the whimsical term "eggs" to represent deployed applications.
#### eggsecutor
Derived from [eggsecutor](https://github.com/lucas-labs/kurv), ๐ค๐ฎ๐ซ๐ฏ adopted the whimsical term "eggs" to represent deployed applications.

### pueue
#### pueue
Insights from [pueue](https://github.com/Nukesor/pueue) were instrumental in helping me understand how to manage processes in Rust.


Expand Down

0 comments on commit 6e0dafb

Please sign in to comment.