Skip to content

Commit 81ab195

Browse files
fiftinfiftin
committed
feat: update docs
1 parent a51bfa8 commit 81ab195

File tree

3 files changed

+120
-71
lines changed

3 files changed

+120
-71
lines changed

‎src/administration-guide/api.md

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,37 @@
22

33
## API reference
44

5-
<div class="warning">
6-
Full API documentation is available in <a href="https://semaphoreui.com/api-docs">API reference</a>.
7-
</div>
5+
Semaphore UI provides two formats of API documentation, so you can choose the one that fits your workflow best:
86

9-
## Creating API token
7+
* [Swagger/OpenAPI](https://semaphoreui.com/api-docs) &mdash; ideal if you prefer an interactive, browser-based experience.
8+
* [Postman](https://api.semaphoreui.com) &mdash; perfect if you want to leverage the full power of the Postman app for testing and exploring the API.
109

11-
### Create API token
10+
Both options include complete documentation of available endpoints, parameters, and example responses.
11+
12+
## Getting Started with the API
13+
14+
To start using the Semaphore API, you need to generate an API token.
15+
This token must be included in the request header as:
16+
17+
```http
18+
Authorization: Bearer YOUR_API_TOKEN
19+
```
20+
21+
### Creating an API Token
22+
23+
There are two ways to create an API token:
24+
- Through the web interface
25+
- Using HTTP request
26+
27+
#### Through the web interface
28+
29+
You can create and manage your API tokens via the Semaphore web UI:
1230

1331
<img style="aspect-ratio: 1920/1440" src="https://www.semaphoreui.com/uploads/v2.14/tokens.webp">
1432

15-
### CLI
33+
#### Using HTTP request
34+
35+
You can also authenticate and generate a session token using a direct HTTP request.
1636

1737
Login to Semaphore (password should be escaped, `slashy\\pass` instead of `slashy\pass` e.g.):
1838

@@ -52,6 +72,12 @@ The command should return something similar to:
5272

5373
`[{"id":"`**`YOUR_ACCESS_TOKEN`**`","created":"2017-03-11T13:13:13Z","expired":false,"user_id":1}]`
5474

75+
## Using token to make API requests
76+
77+
Once you have your API token, include it in the **Authorization** header to authenticate your requests.
78+
79+
### Launch a task
80+
5581
Use this token for launching a task or anything else:
5682

5783
```bash
@@ -63,7 +89,11 @@ curl -v -XPOST \
6389
http://localhost:3000/api/project/1/tasks
6490
```
6591

66-
Expire a token:
92+
## Expiring an API token
93+
94+
If you no longer need the token, you should expire it to keep your account secure.
95+
96+
To manually revoke (expire) an API token, send a DELETE request to the token endpoint:
6797

6898
```bash
6999
curl -v -XDELETE \

‎src/administration-guide/configuration.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Configuration
22

3-
There are following ways to configure Semaphore:
3+
Semaphore can be configured using several methods:
44

5-
* [Configuration file](./configuration/config-file.md)
6-
* [Envrioment variables](./configuration/env-vars.md)
7-
* [Interactive setup](./configuration/snap.md)
8-
* [Snap configuration (deprecated)](./configuration/snap.md)
5+
* [Interactive setup](./configuration/snap.md) &mdash; guided configuration when running Semaphore for the first time. It creates `config.json`.
6+
* [Configuration file](./configuration/config-file.md) &mdash; the primary and most flexible way to configure Semaphore.
7+
* [Envrioment variables](./configuration/env-vars.md) &mdash; useful for containerized or cloud-native deployments.
8+
* [Snap configuration (deprecated)](./configuration/snap.md) &mdash; legacy method used when installing via Snap packages.
99

1010

1111
## Configuration options

‎src/administration-guide/configuration/config-file.md

Lines changed: 78 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,91 @@
11

22
# Configuration file
33

4-
You can use interactive config file generator:
5-
* for [server](https://semaphoreui.com/install/binary/2_12/config)
6-
* for [runner](https://semaphoreui.com/install/binary/2_12/runner).
4+
## Creating configuration file
5+
6+
Semaphore uses a `config.json` file for its core configuration. You can generate this file interactively using built-in tools or through a web-based configurator.
7+
8+
### Generate via CLI
9+
10+
Use the following commands to generate the configuration file interactively:
11+
12+
* For the Semaphore server:
13+
```
14+
semaphore setup
15+
```
16+
* For the Semaphore runner:
17+
```
18+
semaphore runner setup
19+
```
20+
21+
<div class="warning">
22+
For more details about runner configuration, see the <a href="./../runners.md">Runners</a> section.
23+
</div>
24+
25+
26+
### Generate via Web
27+
28+
Alternatively, you can use the web-based interactive configurator:
29+
* [Server Configurator](https://semaphoreui.com/install/binary/2_13/config)
30+
* [Runner Configurator](https://semaphoreui.com/install/binary/2_13/runner)
31+
32+
## Configuration file example
733

834
Semaphore uses a `config.json` configuration file with following content:
935

1036
```javascript
1137
{
12-
"bolt": {
13-
"host": "/home/ubuntu/semaphore.bolt"
14-
},
15-
"mysql": {
16-
"host": "localhost",
17-
"user": "root",
18-
"pass": "*****",
19-
"name": "semaphore",
20-
"options": {}
21-
},
22-
"postgres": {
23-
"host": "localhost",
24-
"user": "postgres",
25-
"pass": "*****",
26-
"name": "semaphore",
27-
"options": {}
28-
},
29-
"dialect": "postgres",
30-
"port": "",
31-
"interface": "",
32-
"tmp_path": "/tmp/semaphore",
33-
"cookie_hash": "*****",
34-
"cookie_encryption": "*****",
35-
"access_key_encryption": "*****",
36-
"email_sender": "",
37-
"email_host": "",
38-
"email_port": "",
39-
"web_host": "",
40-
"ldap_binddn": "",
41-
"ldap_bindpassword": "",
42-
"ldap_server": "",
43-
"ldap_searchdn": "",
44-
"ldap_searchfilter": "",
45-
"ldap_mappings": {
46-
"dn": "",
47-
"mail": "",
48-
"uid": "",
49-
"cn": ""
50-
},
51-
"telegram_chat": "",
52-
"telegram_token": "",
53-
"concurrency_mode": "",
54-
"max_parallel_tasks": 0,
55-
"email_alert": false,
56-
"telegram_alert": false,
57-
"slack_alert": false,
58-
"slack_url": "",
59-
"microsoft_teams_alert": false,
60-
"microsoft_teams_url": "",
61-
"rocketchat_alert": false,
62-
"rocketchat_url": "",
63-
"ldap_enable": false,
64-
"ldap_needtls": false
65-
}
38+
"mysql_test": {
39+
"host": "127.0.0.1:3306",
40+
"user": "root",
41+
"pass": "***",
42+
"name": "semaphore"
43+
},
44+
45+
"dialect": "mysql",
46+
47+
"git_client": "go_git",
48+
49+
"auth": {
50+
"totp": {
51+
"enabled": false,
52+
"allow_recovery": true
53+
}
54+
},
55+
56+
"use_remote_runner": true,
57+
"runner_registration_token": "73fs***",
58+
59+
"tmp_path": "/tmp/semaphore",
60+
"cookie_hash": "96Nt***",
61+
"cookie_encryption": "x0bs***",
62+
"access_key_encryption": "j1ia***",
63+
64+
"max_tasks_per_template": 3,
65+
66+
"log": {
67+
"events": {
68+
"enabled": true,
69+
"path": "./events.log"
70+
}
71+
},
72+
73+
"process": {
74+
"chroot": "/opt/semaphore/sandbox"
75+
}
76+
}
6677
```
6778

68-
Usage:
79+
## Configuration file usage
80+
81+
* For Semaphore server:
6982

7083
```bash
7184
semaphore server --config ./config.json
72-
```
85+
```
86+
87+
* For Semaphore runner:
88+
89+
```bash
90+
semaphore runner start --config ./config.json
91+
```

0 commit comments

Comments
 (0)