Skip to content

Commit 2a84bbe

Browse files
acebergaceberg
committed
README and docs
1 parent 5a677b2 commit 2a84bbe

File tree

3 files changed

+163
-7
lines changed

3 files changed

+163
-7
lines changed

‎README.md

+62-7
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
<h1><a href="https://github.com/aceberg/AnyAppStart">
22
<img src="https://raw.githubusercontent.com/aceberg/AnyAppStart/main/assets/logo.png" width="20" />
33
</a>AnyAppStart</h1>
4-
<br/>
54

6-
Universal app to `Start`/`Stop`/`Restart`/`View Logs` for any Type of service (Docker, Systemd, VMs, remote, user scripts)
5+
[![Main-Docker](https://github.com/aceberg/AnyAppStart/actions/workflows/main-docker.yml/badge.svg)](https://github.com/aceberg/AnyAppStart/actions/workflows/main-docker.yml)
6+
![GitHub License](https://img.shields.io/github/license/aceberg/AnyAppStart)
7+
8+
Universal app to `Start`/`Stop`/`Restart`/`View Logs` for any Type of service (Docker, Systemd, VMs, LXC, remote, user scripts)
79

810
- Backend: `Go`, Frontend: `React`, `TypeScript`, `MobX`
911
- Small lightweight app, easy to set up and configure
@@ -21,13 +23,13 @@ Universal app to `Start`/`Stop`/`Restart`/`View Logs` for any Type of service (D
2123

2224
</details>
2325

24-
## Install
26+
## Installation
2527
<details>
2628
<summary>Expand</summary>
2729

2830
> :warning: **Warning**
2931
> 1. There is Docker image available, but inside the container only Docker Type will work, which kinda defeats the purpose of this app. So installing binary is recommended.
30-
> 2. There is no built-in auth in this app, so make sure to restrict access to it with firewall and/or SSO (Authelia) or simple [ForAuth](https://github.com/aceberg/ForAuth)
32+
> 2. There is no built-in auth in this app, so make sure to restrict access to it with firewall and/or SSO (like Authelia) or simple [ForAuth](https://github.com/aceberg/ForAuth)
3133
3234
### Binary
3335
All binary packages can be found in [latest](https://github.com/aceberg/AnyAppStart/releases/latest) release. There are `.deb`, `.rpm`, `.apk` (Alpine Linux) and `.tar.gz` files.
@@ -37,18 +39,62 @@ Supported architectures: `amd64`, `i386`, `arm_v5`, `arm_v6`, `arm_v7`, `arm64`.
3739
For `amd64` there is a `deb` repo [available](https://github.com/aceberg/ppa)
3840

3941
### Docker
40-
For demo purpose, mostly.
42+
For demo purposes, mostly.
4143
```sh
4244
docker run --name AnyAppStart \
4345
-e "TZ=$YOURTIMEZONE" \
44-
-v ~/.dockerdata/AnyAppStart:/data/AnyAppStart \
45-
-v /var/run/docker.sock:/var/run/docker.sock \
46+
-v ~/.dockerdata/AnyAppStart:/data/AnyAppStart \ # yaml files here
47+
-v /var/run/docker.sock:/var/run/docker.sock \ # mount docker
4648
-p 8855:8855 \
4749
aceberg/anyappstart
4850
```
4951

5052
</details>
5153

54+
## Usage
55+
<details>
56+
<summary>Expand</summary>
57+
58+
To run AnyAppStart as user, enable and start it:
59+
```sh
60+
sudo systemctl enable --now AnyAppStart@$USER.service
61+
```
62+
After, you need to fill `types.yaml` file, either manually by clicking `Add Type` in GUI Types menu, or by copying this [types.yaml](https://github.com/aceberg/AnyAppStart/blob/main/example/types.yaml) example to `~/.config/AnyAppStart/` (or `/etc/AnyAppStart/` for root)
63+
```yaml
64+
Docker:
65+
Logs: docker logs $ITEMNAME
66+
Restart: docker restart $ITEMNAME
67+
Start: docker start $ITEMNAME
68+
State: docker ps --filter status=running | grep $ITEMNAME
69+
Stop: docker stop $ITEMNAME
70+
Systemd:
71+
Logs: sudo systemctl status $ITEMNAME
72+
Restart: sudo systemctl restart $ITEMNAME
73+
Start: sudo systemctl start $ITEMNAME
74+
State: sudo systemctl | grep running | grep $ITEMNAME
75+
Stop: sudo systemctl stop $ITEMNAME
76+
VM:
77+
Logs: sudo journalctl -u libvirtd.service
78+
Restart: sudo virsh rebool $ITEMNAME
79+
Start: sudo virsh start $ITEMNAME
80+
State: sudo virsh list --state-running | grep $ITEMNAME
81+
Stop: sudo virsh shutdown $ITEMNAME
82+
ssh-Docker:
83+
Logs: ssh remote-host-ip -f docker logs $ITEMNAME
84+
Restart: ssh remote-host-ip -f docker restart $ITEMNAME
85+
Start: ssh remote-host-ip -f docker start $ITEMNAME
86+
State: ssh remote-host-ip -f docker ps --filter status=running | grep $ITEMNAME
87+
Stop: ssh remote-host-ip -f docker stop $ITEMNAME
88+
ssh-Systemd:
89+
Logs: ssh remote-host-ip -f sudo systemctl status $ITEMNAME
90+
Restart: ssh remote-host-ip -f sudo systemctl restart $ITEMNAME
91+
Start: ssh remote-host-ip -f sudo systemctl start $ITEMNAME
92+
State: ssh remote-host-ip -f sudo systemctl | grep running | grep $ITEMNAME
93+
Stop: ssh remote-host-ip -f systemctl stop $ITEMNAME
94+
```
95+
96+
</details>
97+
5298
## Config
5399
<details>
54100
<summary>Expand</summary>
@@ -74,6 +120,15 @@ aceberg/anyappstart
74120
75121
</details>
76122
123+
## Build (for devs) and API
124+
<details>
125+
<summary>Expand</summary>
126+
127+
- API: [docs/API.md](docs/API.md)
128+
- Build: [docs/BUILD.md](docs/BUILD.md)
129+
130+
</details>
131+
77132
## Thanks
78133
<details>
79134
<summary>Expand</summary>

‎docs/API.md

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
## API
2+
```http
3+
GET /api/conf
4+
```
5+
Get app config
6+
7+
8+
```http
9+
GET /api/exec?name=NAME&type=TYPE&exec=EXEC
10+
```
11+
Execute a command, where
12+
- `NAME` - Item name
13+
- `TYPE` - Item Type
14+
- `EXEC` - one of the commands: Start, Stop, Restart, Logs, State
15+
16+
Returns:
17+
- `Ok` - `true` or, if error occurred `false`
18+
- `Out` - command output
19+
20+
<details>
21+
<summary>Example</summary>
22+
23+
```sh
24+
curl "http://0.0.0.0:8855/api/exec?name=wyl&type=Docker&exec=Start"
25+
```
26+
```json
27+
{
28+
"Ok": true,
29+
"Out": "wyl\n"
30+
}⏎
31+
```
32+
33+
</details>
34+
<br>
35+
36+
```http
37+
GET /api/items
38+
```
39+
Get all Items with their current states
40+
41+
```http
42+
GET /api/types
43+
```
44+
Get all Types
45+
46+
```http
47+
POST /api/conf
48+
```
49+
Save config variable `conf`. Example: `data.set('conf', JSON.stringify(conf))`
50+
```http
51+
POST /api/item
52+
```
53+
Edit Item. Variables:
54+
- `old` - old Item
55+
- `new` - new Item (empty Name to delete Item)
56+
```http
57+
POST /api/type
58+
```
59+
Edit Type. Variables:
60+
- `old` - old Type
61+
- `new` - new Type (empty Name to delete Type)

‎docs/BUILD.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# For developers
2+
3+
This app has separate frontend (`React`) and backend (`Go`). You need to run both of them to see modifications while editing the code.
4+
5+
## Dev
6+
7+
1. Backend
8+
```sh
9+
cd backend/ #
10+
make check # check golang code
11+
make run # run backend
12+
```
13+
The backend needs to be restarted to apply any modifications to it!
14+
15+
2. Frontend
16+
```sh
17+
cd frontend/
18+
npm i # install node modules
19+
npm run dev # run frontend
20+
```
21+
Make sure the `api` port in `frontend/src/functions/api.tsx` is the same the backend uses.
22+
23+
## Build
24+
To build the app in a single file, there is a `frontend/Makefile`:
25+
```sh
26+
cd frontend/
27+
make all
28+
```
29+
Edit the `api` port in the Makefile if needed.
30+
31+
Then I just push the code to Github and let Actions build Docker and Binary files for me=)
32+
33+
### Build locally
34+
To build binary locally, after the steps above, run:
35+
36+
```sh
37+
cd backend/
38+
make go-build
39+
```
40+
Binary file will be in `backend/tmp/AnyAppStart`

0 commit comments

Comments
 (0)