Skip to content

Commit 60a8bfb

Browse files
DragoryDragory
committed
docs: update repository docs; add migration guides
1 parent f5c8b94 commit 60a8bfb

9 files changed

+207
-176
lines changed

‎DEVELOPMENT.md

+1-71
Original file line numberDiff line numberDiff line change
@@ -1,71 +1 @@
1-
# Zeppelin development environment
2-
Zeppelin's development environment runs entirely within a Docker container.
3-
Below you can find instructions for setting up the environment and getting started with development!
4-
5-
**Note:** If you'd just like to run the bot for your own server, see 👉 **[PRODUCTION.md](./PRODUCTION.md)** 👈
6-
7-
## Starting the development environment
8-
9-
### Using VSCode devcontainers
10-
1. Install Docker
11-
2. Make a copy of `.env.example` called `.env`
12-
3. Fill in the missing values in `.env`
13-
4. In VSCode: Install the `Remote - Containers` plugin
14-
5. In VSCode: Run `Remote-Containers: Open Folder in Container...` and select the Zeppelin folder
15-
16-
### Using VSCode remote SSH plugin
17-
1. Install Docker
18-
2. Make a copy of `.env.example` called `.env`
19-
3. Fill in the missing values in `.env`
20-
4. Run `docker compose -f docker-compose.development.yml up` to start the development environment
21-
5. In VSCode: Install the `Remote - SSH` plugin
22-
6. In VSCode: Run `Remote-SSH: Connect to Host...`
23-
* As the address, use `[email protected]:3002` (where `3002` matches `DOCKER_DEV_SSH_PORT` in `.env`)
24-
* Use the password specified in `.env` as `DOCKER_DEV_SSH_PASSWORD`
25-
7. In VSCode: Once connected, click `Open folder...` and select `/home/ubuntu/zeppelin`
26-
27-
### Using JetBrains Gateway
28-
1. Install Docker
29-
2. Make a copy of `.env.example` called `.env`
30-
3. Fill in the missing values in `.env`
31-
4. Run `docker compose -f docker-compose.development.yml up` to start the development environment
32-
5. Choose `Connect via SSH` and create a new connection:
33-
* Username: `ubuntu`
34-
* Host: `127.0.0.1`
35-
* Port: `3002` (matching the `DOCKER_DEV_SSH_PORT` value in `.env`)
36-
6. Click `Check Connection and Continue` and enter the password specified in `.env` as `DOCKER_DEV_SSH_PASSWORD` when asked
37-
7. In the next pane:
38-
* IDE version: WebStorm, PHPStorm, or IntelliJ IDEA
39-
* Project directory: `/home/ubuntu/zeppelin`
40-
8. Click `Download and Start IDE`
41-
42-
### Using any other IDE with SSH development support
43-
1. Install Docker
44-
2. Make a copy of `.env.example` called `.env`
45-
3. Fill in the missing values in `.env`
46-
4. Run `docker compose -f docker-compose.development.yml up` to start the development environment
47-
5. Use the following credentials for connecting with your IDE:
48-
* Host: `127.0.0.1`
49-
* Port: `3002` (matching the `DOCKER_DEV_SSH_PORT` value in `.env`)
50-
* Username: `ubuntu`
51-
* Password: As specified in `.env` as `DOCKER_DEV_SSH_PASSWORD`
52-
53-
## Starting the project
54-
55-
### Starting the backend (bot + api)
56-
These commands are run inside the dev container. You should be able to open a terminal in your IDE after connecting.
57-
58-
1. `cd ~/zeppelin/backend`
59-
2. `npm ci`
60-
3. `npm run migrate-dev`
61-
4. `npm run watch`
62-
63-
### Starting the dashboard
64-
These commands are run inside the dev container. You should be able to open a terminal in your IDE after connecting.
65-
66-
1. `cd ~/zeppelin/dashboard`
67-
2. `npm ci`
68-
3. `npm run watch-build`
69-
70-
### Opening the dashboard
71-
Browse to https://localhost:3300 to view the dashboard
1+
Moved to [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)

‎MANAGEMENT.md

+1-34
Original file line numberDiff line numberDiff line change
@@ -1,34 +1 @@
1-
# Management
2-
After starting Zeppelin -- either in the [development](./DEVELOPMENT.md) or [production](./PRODUCTION.md) environment -- you have several tools available to manage it.
3-
4-
## Note
5-
Make sure to add yourself to the list of staff members (`STAFF`) in `.env` and allow at least one server by default (`DEFAULT_ALLOWED_SERVERS`). Then, invite the bot to the server.
6-
7-
In all examples below, `@Bot` refers to a user mention of the bot user. Make sure to run the commands on a server with the bot, in a channel that the bot can see.
8-
9-
In the command parameters, `<this>` refers to a required parameter (don't include the `< >` symbols) and `[this]` refers to an optional parameter (don't include the `[ ]` symbols). `<this...>` refers to being able to list multiple values, e.g. `value1 value2 value3`.
10-
11-
## Allow a server to invite the bot
12-
Run the following command:
13-
```
14-
@Bot allow_server <serverId> [userId]
15-
```
16-
When specifying a user ID, that user will be given "Bot manager" level access to the server's dashboard, allowing them to manage access for other users.
17-
18-
## Disallow a server
19-
Run the following command:
20-
```
21-
@Bot disallow_server <serverId>
22-
```
23-
24-
## Grant access to a server's dashboard
25-
Run the following command:
26-
```
27-
@Bot add_dashboard_user <serverId> <userId...>
28-
```
29-
30-
## Remove access to a server's dashboard
31-
Run the following command:
32-
```
33-
@Bot remove_dashboard_user <serverId> <userId...>
34-
```
1+
Moved to [docs/MANAGEMENT.md](docs/MANAGEMENT.md)

‎PRODUCTION.md

+1-67
Original file line numberDiff line numberDiff line change
@@ -1,67 +1 @@
1-
# Zeppelin production environment
2-
Zeppelin's production environment uses Docker. There are a few different ways to run Zeppelin in production:
3-
4-
1. **Standalone**
5-
* The easiest way to get Zeppelin up and running. This setup comes with a built-in database and web server.
6-
2. **Lightweight**
7-
* In case you don't want to use the built-in database and web server. This setup only runs the bot, API, and dashboard themselves. You'll have to provide your own database connection options and set up a proxy server for the API and dashboard.
8-
3. **Manual**
9-
* If you only want to run a specific service, you can use Zeppelin's Dockerfile directly.
10-
11-
## Standalone
12-
13-
### Setup
14-
1. Install Docker on the machine running the bot
15-
2. Make a copy of `.env.example` called `.env`
16-
3. Fill in the missing values in `.env` (including the "PRODUCTION - STANDALONE" section)
17-
18-
**Note:** The dashboard and API are exposed with a self-signed certificate. It is recommended to set up a proxy with a proper certificate in front of them. A popular option for this is [Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/).
19-
20-
### Running the bot
21-
`docker compose -f docker-compose.standalone.yml up -d`
22-
23-
### Shutting the bot down
24-
`docker compose -f docker-compose.standalone.yml down`
25-
26-
### Updating the bot
27-
1. Shut the bot down
28-
2. Update the files (e.g. `git pull`)
29-
3. Rebuild: `docker compose -f docker-compose.standalone.yml build`
30-
4. Run the bot again
31-
32-
### Viewing logs
33-
`docker compose -f docker-compose.standalone.yml logs -t -f`
34-
35-
## Lightweight
36-
37-
### Setup
38-
1. Install Docker on the machine running the bot
39-
2. Make a copy of `.env.example` called `.env`
40-
3. Fill in the missing values in `.env` (including the "PRODUCTION - LIGHTWEIGHT" section)
41-
42-
### Running the bot
43-
`docker compose -f docker-compose.lightweight.yml up -d`
44-
45-
### Shutting the bot down
46-
`docker compose -f docker-compose.lightweight.yml down`
47-
48-
### Updating the bot
49-
1. Shut the bot down
50-
2. Update the files (e.g. `git pull`)
51-
3. Rebuild: `docker compose -f docker-compose.lightweight.yml build`
52-
4. Run the bot again
53-
54-
### Viewing logs
55-
`docker compose -f docker-compose.lightweight.yml logs -t -f`
56-
57-
## Manual
58-
1. Build the Zeppelin image: `docker build --tag 'zeppelin' .`
59-
2. Run the service:
60-
* Bot: `docker run zeppelin npm run start-bot`
61-
* API: `docker run zeppelin npm run start-api`
62-
* Dashboard: `docker run zeppelin npm run start-dashboard`
63-
64-
If you're using an application platform such as Railway, you can simply point it to Zeppelin's repository and it should pick up the Dockerfile from there.
65-
For the start command, you can use the same commands as above: `npm run start-bot`, `npm run start-api`, `npm run start-dashboard`.
66-
67-
**Note:** You'll need to provide the necessary env variables. For example, `docker run --env-file .env zeppelin`
1+
Moved to [docs/PRODUCTION.md](docs/PRODUCTION.md)

‎README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,11 @@ See https://zeppelin.gg/ for more details.
2323
For information on how to use the bot, see https://zeppelin.gg/docs
2424

2525
## Development
26-
See [DEVELOPMENT.md](./DEVELOPMENT.md) for instructions on running the development environment.
26+
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for instructions on running the development environment.
2727

28-
Once you have the environment up and running, see [MANAGEMENT.md](./MANAGEMENT.md) for how to manage your bot.
28+
Once you have the environment up and running, see [docs/MANAGEMENT.md](docs/MANAGEMENT.md) for how to manage your bot.
2929

3030
## Production
31-
See [PRODUCTION.md](./PRODUCTION.md) for instructions on how to run the bot in production.
31+
See [docs/PRODUCTION.md](docs/PRODUCTION.md) for instructions on how to run the bot in production.
3232

33-
Once you have the environment up and running, see [MANAGEMENT.md](./MANAGEMENT.md) for how to manage your bot.
33+
Once you have the environment up and running, see [docs/MANAGEMENT.md](docs/MANAGEMENT.md) for how to manage your bot.

‎docs/DEVELOPMENT.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Zeppelin development environment
2+
3+
⚠️ **Updating from before 30 Mar 2024? See [MIGRATE_DEV.md](./MIGRATE_DEV.md) for instructions.**
4+
5+
Zeppelin's development environment runs entirely within a Docker container.
6+
Below you can find instructions for setting up the environment and getting started with development!
7+
8+
**Note:** If you'd just like to run the bot for your own server, see 👉 **[PRODUCTION.md](./PRODUCTION.md)** 👈
9+
10+
## Starting the development environment
11+
12+
### Using VSCode devcontainers
13+
1. Install Docker
14+
2. Make a copy of `.env.example` called `.env`
15+
3. Fill in the missing values in `.env`
16+
4. In VSCode: Install the `Remote - Containers` plugin
17+
5. In VSCode: Run `Remote-Containers: Open Folder in Container...` and select the Zeppelin folder
18+
19+
### Using VSCode remote SSH plugin
20+
1. Install Docker
21+
2. Make a copy of `.env.example` called `.env`
22+
3. Fill in the missing values in `.env`
23+
4. Run `docker compose -f docker-compose.development.yml up` to start the development environment
24+
5. In VSCode: Install the `Remote - SSH` plugin
25+
6. In VSCode: Run `Remote-SSH: Connect to Host...`
26+
* As the address, use `[email protected]:3002` (where `3002` matches `DEVELOPMENT_SSH_PORT` in `.env`)
27+
* Use the password specified in `.env` as `DEVELOPMENT_SSH_PASSWORD`
28+
7. In VSCode: Once connected, click `Open folder...` and select `/home/ubuntu/zeppelin`
29+
30+
### Using JetBrains Gateway
31+
1. Install Docker
32+
2. Make a copy of `.env.example` called `.env`
33+
3. Fill in the missing values in `.env`
34+
4. Run `docker compose -f docker-compose.development.yml up` to start the development environment
35+
5. Choose `Connect via SSH` and create a new connection:
36+
* Username: `ubuntu`
37+
* Host: `127.0.0.1`
38+
* Port: `3002` (matching the `DEVELOPMENT_SSH_PORT` value in `.env`)
39+
6. Click `Check Connection and Continue` and enter the password specified in `.env` as `DEVELOPMENT_SSH_PASSWORD` when asked
40+
7. In the next pane:
41+
* IDE version: WebStorm, PHPStorm, or IntelliJ IDEA
42+
* Project directory: `/home/ubuntu/zeppelin`
43+
8. Click `Download and Start IDE`
44+
45+
### Using any other IDE with SSH development support
46+
1. Install Docker
47+
2. Make a copy of `.env.example` called `.env`
48+
3. Fill in the missing values in `.env`
49+
4. Run `docker compose -f docker-compose.development.yml up` to start the development environment
50+
5. Use the following credentials for connecting with your IDE:
51+
* Host: `127.0.0.1`
52+
* Port: `3002` (matching the `DEVELOPMENT_SSH_PORT` value in `.env`)
53+
* Username: `ubuntu`
54+
* Password: As specified in `.env` as `DEVELOPMENT_SSH_PASSWORD`
55+
56+
## Starting the project
57+
These commands are run inside the dev container. You should be able to open a terminal in your IDE after connecting.
58+
59+
### 1. Install dependencies
60+
61+
1. `npm ci`
62+
63+
### Starting the backend (bot + api)
64+
65+
1. `cd ~/zeppelin/backend`
66+
2. `npm run watch`
67+
68+
### Starting the dashboard
69+
70+
1. `cd ~/zeppelin/dashboard`
71+
2. `npm run watch`
72+
73+
### Opening the dashboard
74+
Browse to https://localhost:3300 to view the dashboard

‎docs/MANAGEMENT.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Management
2+
After starting Zeppelin -- either in the [development](./DEVELOPMENT.md) or [production](./PRODUCTION.md) environment -- you have several tools available to manage it.
3+
4+
## Note
5+
Make sure to add yourself to the list of staff members (`STAFF`) in `.env` and allow at least one server by default (`DEFAULT_ALLOWED_SERVERS`). Then, invite the bot to the server.
6+
7+
In all examples below, `@Bot` refers to a user mention of the bot user. Make sure to run the commands on a server with the bot, in a channel that the bot can see.
8+
9+
In the command parameters, `<this>` refers to a required parameter (don't include the `< >` symbols) and `[this]` refers to an optional parameter (don't include the `[ ]` symbols). `<this...>` refers to being able to list multiple values, e.g. `value1 value2 value3`.
10+
11+
## Allow a server to invite the bot
12+
Run the following command:
13+
```
14+
@Bot allow_server <serverId> [userId]
15+
```
16+
When specifying a user ID, that user will be given "Bot manager" level access to the server's dashboard, allowing them to manage access for other users.
17+
18+
## Disallow a server
19+
Run the following command:
20+
```
21+
@Bot disallow_server <serverId>
22+
```
23+
24+
## Grant access to a server's dashboard
25+
Run the following command:
26+
```
27+
@Bot add_dashboard_user <serverId> <userId...>
28+
```
29+
30+
## Remove access to a server's dashboard
31+
Run the following command:
32+
```
33+
@Bot remove_dashboard_user <serverId> <userId...>
34+
```

‎docs/MIGRATE_DEV.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Migrating from a version before 30 Mar 2024
2+
Zeppelin's development environment was restructured on 30 Mar 2024. Here's a list of changes to keep in mind when updating to the new version:
3+
* Env variables in `backend/bot.env` and `backend/api.env` have been consolidated into `.env` at the root directory
4+
* It is recommended to create a fresh `.env` file based on `.env.example`
5+
* MySQL data is no longer symlinked to `docker/development/data`. This means that when you start the dev env for the first time, the database will also be created fresh.
6+
* The data is now saved to a named Docker volume instead
7+
* If you need to move over the old data, check the `volumes` section of the `mysql` service in [docker-compose.development.yml](../docker-compose.development.yml) for instructions.
8+
* The recommended dashboard watch command has changed from `npm run watch-build` to `npm run watch`
9+
* If you had made changes to the home folder of the devenv (i.e. `/home/ubuntu` inside the `devenv` container), e.g. by adding SSH keys to `.ssh`, these will need to be re-applied
10+
* For SSH specifically, it is recommended to use SSH agent forwarding rather than copying key files directly to the container. VS Code and Jetbrains Gateway handle this for you automatically.

‎docs/MIGRATE_PROD.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Migrating from a version before 30 Mar 2024
2+
Zeppelin's production environment was restructured on 30 Mar 2024. Here's a list of changes to keep in mind when updating to the new version:
3+
* The docker compose file for the production environment is now called `docker-compose.standalone.yml`. There is also a `docker-compose.lightweight.yml` file for different use cases, see [PRODUCTION.md](PRODUCTION.md) for details.
4+
* Env variables in `backend/bot.env` and `backend/api.env` have been consolidated into `.env` at the root directory
5+
* It is recommended to create a fresh `.env` file based on `.env.example`
6+
* MySQL data is no longer symlinked to `docker/production/data`. This means that when you start the bot for the first time, the database will also be created fresh.
7+
* To migrate your data, connect to the database and import a database dump
8+
* If you did not take a backup of your data before updating, check the `volumes` section of the `mysql` service in [docker-compose.production.yml](../docker-compose.production.yml) for instructions on loading the old data folder
9+
* When the production Docker image is being built, files from the bot's folder are now *copied* rather than linked. This means that if you make changes to the files, you need to rebuild the services to see the changes.
10+
11+
If you need help with any of these steps, please join us on the Zeppelin self-hosting community The Hangar at [https://discord.gg/uTcdUmF6Q7](https://discord.gg/uTcdUmF6Q7)!

‎docs/PRODUCTION.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Zeppelin production environment
2+
3+
⚠️ **Updating from before 30 Mar 2024? See [MIGRATE_PROD.md](./MIGRATE_PROD.md) for instructions.**
4+
5+
Zeppelin's production environment uses Docker. There are a few different ways to run Zeppelin in production:
6+
7+
1. **Standalone**
8+
* The easiest way to get Zeppelin up and running. This setup comes with a built-in database and web server.
9+
2. **Lightweight**
10+
* In case you don't want to use the built-in database and web server. This setup only runs the bot, API, and dashboard themselves. You'll have to provide your own database connection options and set up a proxy server for the API and dashboard.
11+
3. **Manual**
12+
* If you only want to run a specific service, you can use Zeppelin's Dockerfile directly.
13+
14+
## Standalone
15+
16+
### Setup
17+
1. Install Docker on the machine running the bot
18+
2. Make a copy of `.env.example` called `.env`
19+
3. Fill in the missing values in `.env` (including the "PRODUCTION - STANDALONE" section)
20+
21+
**Note:** The dashboard and API are exposed with a self-signed certificate. It is recommended to set up a proxy with a proper certificate in front of them. A popular option for this is [Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/).
22+
23+
### Running the bot
24+
`docker compose -f docker-compose.standalone.yml up -d`
25+
26+
### Shutting the bot down
27+
`docker compose -f docker-compose.standalone.yml down`
28+
29+
### Updating the bot
30+
1. Shut the bot down
31+
2. Update the files (e.g. `git pull`)
32+
3. Rebuild: `docker compose -f docker-compose.standalone.yml build`
33+
4. Run the bot again
34+
35+
### Viewing logs
36+
`docker compose -f docker-compose.standalone.yml logs -t -f`
37+
38+
## Lightweight
39+
40+
### Setup
41+
1. Install Docker on the machine running the bot
42+
2. Make a copy of `.env.example` called `.env`
43+
3. Fill in the missing values in `.env` (including the "PRODUCTION - LIGHTWEIGHT" section)
44+
45+
### Running the bot
46+
`docker compose -f docker-compose.lightweight.yml up -d`
47+
48+
### Shutting the bot down
49+
`docker compose -f docker-compose.lightweight.yml down`
50+
51+
### Updating the bot
52+
1. Shut the bot down
53+
2. Update the files (e.g. `git pull`)
54+
3. Rebuild: `docker compose -f docker-compose.lightweight.yml build`
55+
4. Run the bot again
56+
57+
### Viewing logs
58+
`docker compose -f docker-compose.lightweight.yml logs -t -f`
59+
60+
## Manual
61+
1. Build the Zeppelin image: `docker build --tag 'zeppelin' .`
62+
2. Run the service:
63+
* Bot: `docker run zeppelin npm run start-bot`
64+
* API: `docker run zeppelin npm run start-api`
65+
* Dashboard: `docker run zeppelin npm run start-dashboard`
66+
67+
If you're using an application platform such as Railway, you can simply point it to Zeppelin's repository and it should pick up the Dockerfile from there.
68+
For the start command, you can use the same commands as above: `npm run start-bot`, `npm run start-api`, `npm run start-dashboard`.
69+
Make sure to also run migrations when you update the bot.
70+
71+
**Note:** You'll need to provide the necessary env variables. For example, `docker run --env-file .env zeppelin`

0 commit comments

Comments
 (0)