Skip to content

Commit 4752786

Browse files
ibodrovibodrov
committed
docs: move core docs into main repository
Copy core documentation from concord-website into the main repository. Use mdBook for building.
1 parent 376055e commit 4752786

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

84 files changed

+17544
-0
lines changed

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
book
2+
index.html

‎docs/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Concord Documentation
2+
3+
This documentation covers Concord, a workflow server and orchestration engine that connects different
4+
systems together using scenarios and plugins.
5+
6+
Concord provides a comprehensive platform for process automation, featuring:
7+
8+
- **Process Management**: execute workflows in isolated environments
9+
- **Project Organization**: group processes with shared configuration and resources
10+
- **Security**: built-in secrets management and team-based authorization
11+
- **Extensibility**: rich plugin ecosystem for system integration
12+
13+
## Building
14+
15+
To build and view the documentation:
16+
17+
1. Install the required tools:
18+
```shell
19+
cargo install mdbook mdbook-variables
20+
```
21+
22+
2. Serve the documentation locally:
23+
```shell
24+
mdbook serve
25+
```
26+
27+
The documentation will be available at `http://localhost:3000`
28+
29+
The built documentation is output to the `book/` directory.

‎docs/book.toml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
[book]
2+
authors = ["Concord Authors"]
3+
language = "en"
4+
src = "src"
5+
title = "Concord"
6+
7+
[preprocessor.variables.variables.site]
8+
concord_core_version = "2.32.0"
9+
concord_source = "https://github.com/walmartlabs/concord/"
10+
concord_plugins_source = "https://github.com/walmartlabs/concord-plugins/"
11+
concord_plugins_v1_docs = "https://concord.walmartlabs.com/docs/plugins-v1"
12+
concord_plugins_v2_docs = "https://concord.walmartlabs.com/docs/plugins-v2"
13+
14+
[output.html]
15+
default-theme = "light"

‎docs/src/SUMMARY.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Summary
2+
3+
[Introduction](../README.md)
4+
5+
# User Guide
6+
7+
- [Overview](./getting-started/index.md)
8+
- [Quick Start](./getting-started/quickstart.md)
9+
- [Installation](./getting-started/installation.md)
10+
- [Configuration](./getting-started/configuration.md)
11+
- [Processes](./getting-started/processes.md)
12+
- [Projects](./getting-started/projects.md)
13+
- [Forms](./getting-started/forms.md)
14+
- [Scripting](./getting-started/scripting.md)
15+
- [Security](./getting-started/security.md)
16+
- [Tasks](./getting-started/tasks.md)
17+
- [Organizations and Teams](./getting-started/orgs.md)
18+
- [Policies](./getting-started/policies.md)
19+
- [JSON Store](./getting-started/json-store.md)
20+
- [Node Roster](./getting-started/node-roster.md)
21+
- [Development](./getting-started/development.md)
22+
23+
# Reference
24+
25+
- [Processes](./processes-v2/index.md)
26+
- [Configuration](./processes-v2/configuration.md)
27+
- [Flows](./processes-v2/flows.md)
28+
- [Migration from v1](./processes-v2/migration.md)
29+
- [Imports](./processes-v2/imports.md)
30+
- [Profiles](./processes-v2/profiles.md)
31+
- [Resources](./processes-v2/resources.md)
32+
- [Tasks](./processes-v2/tasks.md)
33+
- [Plugins](./plugins/index.md)
34+
- [Ansible](./plugins/ansible.md)
35+
- [Asserts](./plugins/asserts.md)
36+
- [Concord](./plugins/concord.md)
37+
- [Crypto](./plugins/crypto.md)
38+
- [Datetime](./plugins/datetime.md)
39+
- [Docker](./plugins/docker.md)
40+
- [Files](./plugins/files.md)
41+
- [HTTP](./plugins/http.md)
42+
- [JSON Store](./plugins/json-store.md)
43+
- [Key-value](./plugins/key-value.md)
44+
- [Lock](./plugins/lock.md)
45+
- [Mocks](./plugins/mocks.md)
46+
- [Node Roster](./plugins/node-roster.md)
47+
- [Resource](./plugins/resource.md)
48+
- [Slack](./plugins/slack.md)
49+
- [Sleep](./plugins/sleep.md)
50+
- [SMTP](./plugins/smtp.md)
51+
- [Triggers](./triggers/index.md)
52+
- [GitHub](./triggers/github.md)
53+
- [Cron](./triggers/cron.md)
54+
- [Manual](./triggers/manual.md)
55+
- [Generic](./triggers/generic.md)
56+
- [OneOps](./triggers/oneops.md)
57+
- [CLI](./cli/index.md)
58+
- [Linting](./cli/linting.md)
59+
- [Running Flows](./cli/running-flows.md)
60+
- [API](./api/index.md)
61+
- [API Key](./api/apikey.md)
62+
- [Checkpoint](./api/checkpoint.md)
63+
- [Form](./api/form.md)
64+
- [JSON Store](./api/json-store.md)
65+
- [Node Roster](./api/node-roster.md)
66+
- [Organization](./api/org.md)
67+
- [Policy](./api/policy.md)
68+
- [Process](./api/process.md)
69+
- [Project](./api/project.md)
70+
- [Repository](./api/repository.md)
71+
- [Role](./api/role.md)
72+
- [Secret](./api/secret.md)
73+
- [Team](./api/team.md)
74+
- [Template](./api/template.md)
75+
- [Trigger](./api/trigger.md)
76+
- [User](./api/user.md)
77+
78+
# Deprecated Features
79+
80+
- [Processes (v1)](./processes-v1/index.md)
81+
- [Configuration](./processes-v1/configuration.md)
82+
- [Flows](./processes-v1/flows.md)
83+
- [Imports](./processes-v1/imports.md)
84+
- [Profiles](./processes-v1/profiles.md)
85+
- [Resources](./processes-v1/resources.md)
86+
- [Tasks](./processes-v1/tasks.md)
87+
- [Templates](./templates/index.md)

‎docs/src/api/apikey.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# API Key
2+
3+
An API Key is specific to a user and allows access to the API with the key
4+
replacing the usage of user credentials for authentication.
5+
6+
The REST API provides support for a number of operations:
7+
8+
- [Create a New API Key](#create-key)
9+
- [List Existing API keys](#list-keys)
10+
- [Delete an Existing API Key](#delete-key)
11+
12+
<a name="create-key"/>
13+
14+
## Create a New API Key
15+
16+
Creates a new API key for a user.
17+
18+
* **URI** `/api/v1/apikey`
19+
* **Method** `POST`
20+
* **Headers** `Authorization`, `Content-Type: application/json`
21+
* **Body**
22+
```json
23+
{
24+
"username": "myLdapUsername",
25+
"userDomain": "optional.domain.com"
26+
}
27+
```
28+
* **Success response**
29+
```
30+
Content-Type: application/json
31+
```
32+
33+
```json
34+
{
35+
"ok": true,
36+
"id": "3b45a52f-91d7-4dd0-8bf6-b06548e0afa5",
37+
"key": "someGeneratedKeyValue"
38+
}
39+
```
40+
* **Example**: create a key, Concord will auto-generate a key name
41+
```
42+
curl -u myLdapUser \
43+
-X POST \
44+
-H "Content-Type: application/json" \
45+
-d '{ "username": "myLdapUser" }' \
46+
https://concord.example.com/api/v1/apikey
47+
```
48+
49+
* **Example**: create a key, specify a key name
50+
```
51+
curl -u myLdapUser \
52+
-X POST \
53+
-H "Content-Type: application/json" \
54+
-d '{ "username": "myLdapUser", "name": "myCustomApiKeyName" }' \
55+
https://concord.example.com/api/v1/apikey
56+
```
57+
58+
* **Example**: create a key when multiple users with the same username exist across domains
59+
```
60+
curl -u [email protected] \
61+
-X POST \
62+
-H "Content-Type: application/json" \
63+
-d '{ "username": "myLdapUser", "userDomain": "example.com" }' \
64+
https://concord.example.com/api/v1/apikey
65+
```
66+
67+
<a name="list-keys"/>
68+
69+
## List Existing API keys
70+
71+
Lists any existing API keys for the user. Only returns metadata, not actual keys.
72+
73+
* **URI** `/api/v1/apikey`
74+
* **Method** `GET`
75+
* **Headers** `Authorization`, `Content-Type: application/json`
76+
* **Body**
77+
none
78+
* **Success response**
79+
```
80+
Content-Type: application/json
81+
```
82+
83+
```json
84+
[
85+
{
86+
"id" : "2505acba-314d-11e9-adf9-0242ac110002",
87+
"userId": "aab8a8e2-2f75-4859-add1-3b8f5d7a6690",
88+
"name" : "key#1"
89+
}, {
90+
"id" : "efd12c7a-3162-11e9-b9c0-0242ac110002",
91+
"userId": "aab8a8e2-2f75-4859-add1-3b8f5d7a6690",
92+
"name" : "myCustomApiKeyName"
93+
}
94+
]
95+
```
96+
* **Example**
97+
```
98+
curl -u myLdapUser \
99+
-H "Content-Type: application/json" \
100+
https://concord.example.com/api/v1/apikey
101+
```
102+
103+
<a name="delete-key"/>
104+
105+
## Delete an existing API key
106+
107+
Removes an existing API key.
108+
109+
* **URI** `/api/v1/apikey/${id}`
110+
* **Method** `DELETE`
111+
* **Headers** `Authorization`
112+
* **Body**
113+
none
114+
* **Success response**
115+
```
116+
Content-Type: application/json
117+
```
118+
119+
```json
120+
{
121+
"result": "DELETED",
122+
"ok": true
123+
}
124+
```
125+
126+
* **Example**
127+
```
128+
curl -u myLdapUser \
129+
-X DELETE \
130+
-H "Content-Type: application/json" \
131+
https://concord.example.com/api/v1/apikey/2505acba-314d-11e9-adf9-0242ac110002
132+
```
133+
134+
<a name="apikey-authorization"/>
135+
136+
# Using an API key to access the Concord API
137+
138+
When accessing the Concord API, the **Authorization** header can be
139+
set with the value of an API key. This replaces the need to authenticate
140+
with user and password.
141+
142+
* **Example**
143+
```
144+
curl \
145+
-H "Content-Type: application/json" \
146+
-H "Authorization: someGeneratedKeyValue" \
147+
https://concord.example.com/api/v1/apikey
148+
```

‎docs/src/api/checkpoint.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Checkpoint
2+
3+
The checkpoint API can be used to list and restore
4+
[checkpoints created in a flow](../processes-v1/flows.md#checkpoints).
5+
6+
- [List Checkpoints](#list)
7+
- [Restore a Process](#restore)
8+
9+
<a name="list"/>
10+
11+
## List Checkpoints
12+
13+
You can access a list of all checkpoints for a specific process, identified by
14+
the `id`, with the REST API.
15+
16+
* **URI** `/api/v1/process/{id}/checkpoint`
17+
* **Method** `GET`
18+
* **Headers** `Authorization`, `Content-Type: application/json`
19+
* **Body**
20+
none
21+
22+
* **Success response**
23+
24+
```
25+
Content-Type: application/json
26+
```
27+
28+
```json
29+
[
30+
{
31+
"id": "...",
32+
"name": "...",
33+
"createdAt": "..."
34+
},
35+
{
36+
"id": "...",
37+
"name": "...",
38+
"createdAt": "..."
39+
},
40+
...
41+
]
42+
```
43+
44+
<a name="restore"/>
45+
46+
## Restore a Process
47+
48+
You can restore a process state from a named checkpoint of a specific process
49+
using the process identifier in the URL and the checkpoint identifier in the
50+
body.
51+
52+
* **URI** `/api/v1/process/{id}/checkpoint/restore`
53+
* **Method** `POST`
54+
* **Headers** `Authorization`, `Content-Type: application/json`
55+
* **Body**
56+
```json
57+
{
58+
"id": "..."
59+
}
60+
```
61+
62+
* **Success response**
63+
64+
```
65+
Content-Type: application/json
66+
```
67+
68+
```json
69+
{
70+
"ok": true
71+
}
72+
```

0 commit comments

Comments
 (0)