Skip to content

Commit

Permalink
docs: add document
Browse files Browse the repository at this point in the history
  • Loading branch information
@siyul-park
siyul-park committed Oct 8, 2024
1 parent af2af58 commit dde76b3
Show file tree
Hide file tree
Showing 5 changed files with 217 additions and 112 deletions.
96 changes: 56 additions & 40 deletions docs/getting_started.md
View file
Original file line number Diff line number Diff line change
@@ -1,134 +1,150 @@
# 🚀 Getting Started

This guide provides detailed instructions on installing, configuring, and managing workflows using the [Command Line Interface (CLI)](../cmd/README.md). It covers the entire process from installation to workflow control and configuration.
This guide will walk you through installing, configuring, and managing workflows using the [Command Line Interface (CLI)](../cmd/README.md). It covers the full process, from installation to controlling and configuring workflows.

## Installing from Source

To begin, set up the [CLI](../cmd/README.md) along with the [built-in extensions](../ext/README.md). Before starting the installation, ensure that [Go 1.23](https://go.dev/doc/install) or higher is installed on your system.
First, set up the [CLI](../cmd/README.md) along with the [core extensions](../ext/README.md). Make sure your system has [Go 1.23](https://go.dev/doc/install) or a later version installed.

### Cloning the Repository
### Clone the Repository

To clone the source code, run:
To download the source code, run the following command in your terminal:

```sh
git clone https://github.com/siyul-park/uniflow
```

Navigate to the cloned directory:
Navigate to the downloaded folder:

```sh
cd uniflow
```

### Installing Dependencies and Building
### Install Dependencies and Build

To install dependencies and build the project, execute:
To install the required dependencies and build the project, run the following commands:

```sh
make init
make build
```

Once the build is complete, the executable will be located in the `dist` folder.
After the build completes, the executable files will be available in the `dist` folder.

### Configuration

You can modify settings flexibly via the `.uniflow.toml` file or system environment variables. Key configuration options include:
Settings can be modified using the `.uniflow.toml` file or system environment variables. The key configuration options are:

| TOML Key | Environment Variable Key | Example |
|-----------------------|----------------------------|----------------------------|
| `database.url` | `DATABASE.URL` | `mem://` or `mongodb://` |
| `database.name` | `DATABASE.NAME` | - |
| `collection.nodes` | `COLLECTION.NODES` | `nodes` |
| `collection.secrets` | `COLLECTION.SECRETS` | `secrets` |
| TOML Key | Environment Variable Key | Example |
|----------------------|--------------------------|-----------------------------|
| `database.url` | `DATABASE.URL` | `mem://` or `mongodb://` |
| `database.name` | `DATABASE.NAME` | - |
| `collection.nodes` | `COLLECTION.NODES` | `nodes` |
| `collection.secrets` | `COLLECTION.SECRETS` | `secrets` |

If using [MongoDB](https://www.mongodb.com/), enable [Change Streams](https://www.mongodb.com/docs/manual/changeStreams/) to allow the engine to track node specifications and secret changes. This requires setting up a [Replica Set](https://www.mongodb.com/docs/manual/replication/).
If you are using [MongoDB](https://www.mongodb.com/), enable [Change Streams](https://www.mongodb.com/docs/manual/changeStreams/) to track resource changes in real time. This requires setting up a [replica set](https://www.mongodb.com/docs/manual/replication/).

## Uniflow
## Using Uniflow

`uniflow` is primarily used to start and manage runtime environments.
`uniflow` is primarily used to start and manage the runtime environment.

### Start
### Start Command

The `start` command initiates the runtime with node specifications for a specific namespace. Basic usage is as follows:
The `start` command executes all node specifications in the specified namespace. If no namespace is provided, the default namespace (`default`) is used.

```sh
./dist/uniflow start --namespace default
```

If the namespace is empty, you can provide initial node specifications using the `--from-nodes` flag:
If the namespace is empty, you can provide an initial node specification using the `--from-nodes` flag:

```sh
./dist/uniflow start --namespace default --from-nodes examples/nodes.yaml
```

To provide initial secrets, use the `--from-secrets` flag:
You can specify an initial secrets file with the `--from-secrets` flag:

```sh
./dist/uniflow start --namespace default --from-secrets examples/secrets.yaml
```

This command executes all node specifications for the specified namespace. If no namespace is specified, the `default` namespace is used.
Charts can be initialized using the `--from-charts` flag:

## Uniflowctl
```sh
./dist/uniflow start --namespace default --from-charts examples/charts.yaml
```

## Using Uniflowctl

`uniflowctl` is used to manage node specifications and secrets within a namespace.
`uniflowctl` is a command used to manage resources within a namespace.

### Apply
### Apply Command

The `apply` command adds or updates node specifications or secrets in a namespace. Usage examples are:
The `apply` command applies the contents of a specified file to the namespace. If no namespace is specified, the `default` namespace is used.

```sh
./dist/uniflowctl apply nodes --namespace default --filename examples/nodes.yaml
```

or
To apply secrets:

```sh
./dist/uniflowctl apply secrets --namespace default --filename examples/secrets.yaml
```

This command applies the contents of the specified file to the namespace. If no namespace is specified, the `default` namespace is used by default.
To apply charts:

```sh
./dist/uniflowctl apply charts --namespace default --filename examples/charts.yaml
```

### Delete
### Delete Command

The `delete` command removes node specifications or secrets from a namespace. Usage examples are:
The `delete` command removes all resources defined in the specified file. If no namespace is specified, the `default` namespace is used.

```sh
./dist/uniflowctl delete nodes --namespace default --filename examples/nodes.yaml
```

or
To delete secrets:

```sh
./dist/uniflowctl delete secrets --namespace default --filename examples/secrets.yaml
```

This command removes all node specifications or secrets defined in the specified file. If no namespace is specified, the `default` namespace is used.
To delete charts:

### Get
```sh
./dist/uniflowctl delete charts --namespace default --filename examples/charts.yaml
```

### Get Command

The `get` command retrieves node specifications or secrets from a namespace. Usage examples are:
The `get` command retrieves all resources in the specified namespace. If no namespace is specified, the `default` namespace is used.

```sh
./dist/uniflowctl get nodes --namespace default
```

or
To retrieve secrets:

```sh
./dist/uniflowctl get secrets --namespace default
```

This command displays all node specifications or secrets for the specified namespace. If no namespace is specified, the `default` namespace is used.
To retrieve charts:

```sh
./dist/uniflowctl get charts --namespace default
```

## HTTP API Integration
## Integrating HTTP API

To modify node specifications through the HTTP API, set up a workflow that exposes this functionality. You can use the `native` node included in the [basic extensions](../ext/README.md):
To modify node specifications via the HTTP API, set up workflows accordingly. You can use the `native` node provided in the [core extensions](../ext/README.md):

```yaml
kind: native
opcode: nodes.create # or nodes.read, nodes.update, nodes.delete
```
To get started, refer to the [workflow example](../examples/system.yaml). You may need to add authentication and authorization processes to this workflow as needed. Typically, such runtime control workflows are defined in the `system` namespace.
Refer to the [workflow examples](../examples/system.yaml) to get started. If needed, you can add authentication and authorization processes. These runtime control workflows are typically defined in the `system` namespace.
76 changes: 46 additions & 30 deletions docs/getting_started_kr.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
# 🚀 시작하기

이 안내서는 [명령줄 인터페이스(CLI)](../cmd/README_kr.md)를 설치하고 구성하며 워크플로우를 관리하는 방법을 자세히 설명합니다. 설치부터 워크플로우 제어 및 설정까지의 전반적인 과정을 다룹니다.
이 가이드는 [명령줄 인터페이스(CLI)](../cmd/README_kr.md)의 설치, 설정, 그리고 워크플로우 관리 방법을 쉽게 따라 할 수 있도록 설명합니다. 설치 과정부터 워크플로우의 제어 및 설정 방법까지, 필요한 모든 단계를 다룹니다.

## 소스에서 설치하기

먼저 [기본 확장 기능](../ext/README_kr.md)과 함께 제공되는 [CLI](../cmd/README_kr.md)를 설정해야 합니다. 설치를 시작하기 전에 시스템에 [Go 1.23](https://go.dev/doc/install) 이상이 설치되어 있는지 확인하세요.
먼저 [기본 확장 기능](../ext/README_kr.md)과 함께 제공되는 [CLI](../cmd/README_kr.md)를 설정해야 합니다. 시작하기 전에, 시스템에 [Go 1.23](https://go.dev/doc/install) 이상의 버전이 설치되어 있는지 확인하세요.

### 리포지토리 클론

소스 코드를 클론하려면 다음 명령어를 실행합니다:
소스 코드를 다운로드하려면, 터미널에서 아래 명령어를 입력하세요:

```sh
git clone https://github.com/siyul-park/uniflow
```

클론한 디렉토리로 이동합니다:
다운로드한 폴더로 이동합니다:

```sh
cd uniflow
```

### 의존성 설치 및 빌드

의존성을 설치하고 프로젝트를 빌드하려면 다음 명령어를 실행합니다:
필요한 의존성을 설치하고 프로젝트를 빌드하려면, 아래 명령어를 실행하세요:

```sh
make init
Expand All @@ -33,7 +33,7 @@ make build

### 설정

`.uniflow.toml` 파일이나 시스템 환경 변수를 통해 설정을 유연하게 변경할 수 있습니다. 주요 구성 옵션은 다음과 같습니다:
설정은 `.uniflow.toml` 파일이나 시스템 환경 변수를 사용해 유연하게 변경할 수 있습니다. 주요 설정 항목은 다음과 같습니다:

| TOML 키 | 환경 변수 키 | 예시 |
|----------------------|-------------------------|----------------------------|
Expand All @@ -42,93 +42,109 @@ make build
| `collection.nodes` | `COLLECTION.NODES` | `nodes` |
| `collection.secrets` | `COLLECTION.SECRETS` | `secrets` |

[MongoDB](https://www.mongodb.com/)를 사용하는 경우, 엔진이 노드 명세 및 시크릿 변경을 추적할 수 있도록 [변경 스트림](https://www.mongodb.com/docs/manual/changeStreams/)을 활성화해야 합니다. 이를 위해 [복제 세트](https://www.mongodb.com/docs/manual/replication/) 설정이 필요합니다.
만약 [MongoDB](https://www.mongodb.com/)를 사용한다면, 리소스의 변경 사항을 실시간으로 추적하기 위해 [변경 스트림](https://www.mongodb.com/docs/manual/changeStreams/)을 활성화해야 합니다. 이를 위해서는 [복제 세트](https://www.mongodb.com/docs/manual/replication/) 설정이 필요합니다.

## Uniflow
## Uniflow 사용하기

`uniflow`는 주로 런타임 환경을 시작하고 관리하는 데 사용됩니다.
`uniflow`는 주로 런타임 환경을 시작하고 관리하는 명령어입니다.

### Start
### Start 명령어

`start` 명령어는 특정 네임스페이스의 노드 명세로 런타임을 시작합니다. 기본 사용법은 다음과 같습니다:
`start` 명령어는 지정된 네임스페이스 내의 모든 노드 명세를 실행합니다. 네임스페이스가 지정되지 않으면 기본적으로 `default` 네임스페이스가 사용됩니다.

```sh
./dist/uniflow start --namespace default
```

네임스페이스가 비어 있는 경우, `--from-nodes` 플래그를 사용하여 초기 노드 명세를 제공할 수 있습니다:
네임스페이스가 비어 있을 경우, 초기 노드 명세를 `--from-nodes` 플래그로 제공할 수 있습니다:

```sh
./dist/uniflow start --namespace default --from-nodes examples/nodes.yaml
```

초기 시크릿을 제공하려면 `--from-secrets` 플래그를 사용할 수 있습니다:
초기 시크릿 파일은 `--from-secrets` 플래그로 설정할 수 있습니다:

```sh
./dist/uniflow start --namespace default --from-secrets examples/secrets.yaml
```

이 명령어는 지정된 네임스페이스의 모든 노드 명세를 실행합니다. 네임스페이스를 지정하지 않으면 `default` 네임스페이스가 사용됩니다.
초기 차트 파일은 `--from-charts` 플래그로 제공할 수 있습니다:

## Uniflowctl
```sh
./dist/uniflow start --namespace default --from-charts examples/charts.yaml
```

## Uniflowctl 사용하기

`uniflowctl`는 네임스페이스 내에서 노드 명세와 시크릿을 관리하는 데 사용됩니다.
`uniflowctl`는 네임스페이스 내에서 리소스를 관리하는 명령어입니다.

### Apply
### Apply 명령어

`apply` 명령어는 네임스페이스에 노드 명세 또는 시크릿을 추가하거나 업데이트합니다. 사용 예시는 다음과 같습니다:
`apply` 명령어는 지정된 파일 내용을 네임스페이스에 적용합니다. 네임스페이스를 지정하지 않으면 기본적으로 `default` 네임스페이스가 사용됩니다.

```sh
./dist/uniflowctl apply nodes --namespace default --filename examples/nodes.yaml
```

또는
시크릿을 적용하려면:

```sh
./dist/uniflowctl apply secrets --namespace default --filename examples/secrets.yaml
```

이 명령어는 지정된 파일의 내용을 네임스페이스에 적용합니다. 네임스페이스를 지정하지 않으면 기본적으로 `default` 네임스페이스가 사용됩니다.
차트를 적용하려면:

```sh
./dist/uniflowctl apply charts --namespace default --filename examples/charts.yaml
```

### Delete
### Delete 명령어

`delete` 명령어는 네임스페이스에서 노드 명세 또는 시크릿을 제거합니다. 사용 예시는 다음과 같습니다:
`delete` 명령어는 지정된 파일에 정의된 모든 리소스를 삭제합니다. 네임스페이스를 지정하지 않으면 기본적으로 `default` 네임스페이스가 사용됩니다.

```sh
./dist/uniflowctl delete nodes --namespace default --filename examples/nodes.yaml
```

또는
시크릿을 삭제하려면:

```sh
./dist/uniflowctl delete secrets --namespace default --filename examples/secrets.yaml
```

이 명령어는 지정된 파일에 정의된 모든 노드 명세 또는 시크릿을 제거합니다. 네임스페이스를 지정하지 않으면 `default` 네임스페이스가 사용됩니다.
차트를 삭제하려면:

### Get
```sh
./dist/uniflowctl delete charts --namespace default --filename examples/charts.yaml
```

### Get 명령어

`get` 명령어는 네임스페이스에서 노드 명세 또는 시크릿을 조회합니다. 사용 예시는 다음과 같습니다:
`get` 명령어는 지정된 네임스페이스 내 모든 리소스를 조회합니다. 네임스페이스가 지정되지 않으면 기본적으로 `default` 네임스페이스가 사용됩니다.

```sh
./dist/uniflowctl get nodes --namespace default
```

또는
시크릿을 조회하려면:

```sh
./dist/uniflowctl get secrets --namespace default
```

이 명령어는 지정된 네임스페이스의 모든 노드 명세 또는 시크릿을 표시합니다. 네임스페이스를 지정하지 않으면 `default` 네임스페이스가 사용됩니다.
차트를 조회하려면:

```sh
./dist/uniflowctl get charts --namespace default
```

## HTTP API 통합

HTTP API를 통해 노드 명세를 수정하려면 해당 기능을 노출하는 워크플로우를 설정해야 합니다. 이를 위해 [기본 확장](../ext/README_kr.md)에 포함된 `native` 노드를 활용할 수 있습니다:
HTTP API를 통해 노드 명세를 수정하려면, 관련 워크플로우를 설정해야 합니다. 이를 위해 [기본 확장](../ext/README_kr.md)에 포함된 `native` 노드를 사용할 수 있습니다:

```yaml
kind: native
opcode: nodes.create # 또는 nodes.read, nodes.update, nodes.delete
```
시작하려면 [워크플로우 예제](../examples/system.yaml)를 참고하세요. 필요에 따라 이 워크플로우에 인증 및 권한 부여 프로세스를 추가할 수 있습니다. 일반적으로 이러한 런타임 제어 워크플로우는 `system` 네임스페이스에 정의됩니다.
시작하려면 [워크플로우 예제](../examples/system.yaml)를 참고하세요. 필요한 경우, 인증 및 권한 관리 프로세스를 추가할 수 있습니다. 이러한 런타임 제어 워크플로우는 보통 `system` 네임스페이스에 정의됩니다.
Loading

0 comments on commit dde76b3

Please sign in to comment.