Skip to content

Commit 82ea7d6

Browse files
lancepiochlancepioch
authored
Merge pull request #113 from Morpheus636/panel-in-docker
Add documentation for running the panel in Docker
2 parents 590def7 + 2bc21ba commit 82ea7d6

File tree

4 files changed

+190
-42
lines changed

4 files changed

+190
-42
lines changed

‎docs/guides/docker.mdx

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import Admonition from '@theme/Admonition';
2+
3+
# Installing Docker
4+
5+
For a quick install of Docker CE, you can use the command below:
6+
7+
```sh
8+
curl -sSL https://get.docker.com/ | CHANNEL=stable sudo sh
9+
```
10+
11+
<Admonition type="info" title="Installing Docker CE">
12+
If the above command does not work, please refer to the [official Docker documentation](https://docs.docker.com/engine/install/) on how to install Docker CE on your server.
13+
</Admonition>
14+
15+
## Start Docker on Boot
16+
17+
If you are on an operating system with systemd (Ubuntu 16+, Debian 8+, CentOS 7+) run the command below to have Docker start when you boot your machine.
18+
19+
```sh
20+
sudo systemctl enable --now docker
21+
```
22+
23+
## Enabling Swap
24+
25+
On most systems, Docker will be unable to setup swap space by default. You can confirm this by running `docker info` and looking for the output of `WARNING: No swap limit support` near the bottom.
26+
27+
Enabling swap is entirely optional, but we recommended doing it if you will be hosting for others and to prevent OOM errors.
28+
29+
To enable swap, open `/etc/default/grub` as a root user and find the line starting with `GRUB_CMDLINE_LINUX_DEFAULT`. Make
30+
sure the line includes `swapaccount=1` somewhere inside the double-quotes.
31+
32+
After that, run `sudo update-grub` followed by `sudo reboot` to restart the server and have swap enabled.
33+
Below is an example of what the line should look like, _do not copy this line verbatim. It often has additional OS-specific parameters._
34+
35+
```text
36+
GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1"
37+
```
38+
39+
<Admonition type="info" title="GRUB Configurations">
40+
Some Linux distros may ignore `GRUB_CMDLINE_LINUX_DEFAULT`.
41+
Therefore you might have to use `GRUB_CMDLINE_LINUX` instead should the above variable not work for you.
42+
</Admonition>

‎docs/panel/advanced/docker.mdx

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Docker
2+
3+
Pelican provides pre-built Docker images via GitHub Packages. `ghcr.io/pelican-dev/panel:latest` is the current latest release, and `ghcr.io/pelican-dev/panel:main` is built automatically from the current `main` branch. Deploying the panel in Docker is still a work in progress. While the plan is to make Docker the preferred installation method, we currently recommend the [standard deployment instructions](/docs/panel/getting-started)
4+
5+
This guide requires Docker CE. (Docker Compose has been included in the Docker CLI since v2. Docker Compose v1 is unsupported.) For instructions on installing and configuring Docker, see the [installation guide](/docs/guides/docker).
6+
7+
## Basics
8+
9+
The easiest deployment method is using the standard `compose.yml` file.
10+
11+
This configuration includes an integrated web server that will automatically obtain SSL certificates if you are serving over HTTPS. For the database, it assumes you want to use SQLite (or you have an external database server to configure using the installer.) It also assumes you intend to use the Filesystem driver for cache, filesystem or database driver for session, and database driver for queue (or you have an external Redis server to configure using the installer.) If you want to use other options built into Docker, see [Advanced Options](#advanced-options).
12+
13+
### Create compose.yml
14+
15+
```yml {17,18} title="compose.yml"
16+
services:
17+
panel:
18+
image: ghcr.io/pelican-dev/panel:latest
19+
restart: always
20+
networks:
21+
- default
22+
ports:
23+
- "80:80"
24+
- "443:443"
25+
extra_hosts:
26+
- "host.docker.internal:host-gateway"
27+
volumes:
28+
- pelican-data:/pelican-data
29+
- pelican-logs:/var/www/html/storage/logs
30+
environment:
31+
XDG_DATA_HOME: /pelican-data
32+
APP_URL: "http://localhost"
33+
ADMIN_EMAIL: "USEYOUROWNEMAILHERE@example.com"
34+
35+
volumes:
36+
pelican-data:
37+
pelican-logs:
38+
39+
networks:
40+
default:
41+
ipam:
42+
config:
43+
- subnet: 172.20.0.0/16
44+
```
45+
46+
### Set Required Environment Variables
47+
48+
1. Set `APP_URL` to the base URL your panel will be reachable on, including the protocol (https:// or http://) and port.
49+
- Note that Caddy, the integrated webserver, will serve a 308 redirect to any requests on port 80 if the `APP_URL` begins with `https://`. If your final site will be reachable over HTTPS but TLS (SSL) will be handled and terminated by an upstream server, such as a reverse proxy, you will need to use a [custom caddyfile](#custom-caddyfile).
50+
2. Set the `ADMIN_EMAIL` to your email address. Caddy will use this email address to generate a LetsEncrypt SSL certificate if you are serving via HTTPS.
51+
52+
Now, close and save changes to `compose.yml`.
53+
54+
### Starting
55+
56+
From the directory in which the compose file is located, run:
57+
58+
```sh
59+
docker compose up -d
60+
```
61+
62+
### Back Up Your Encryption Key
63+
64+
The first time the container starts, it will generate an `APP_KEY` which is used as an encryption key. This will be saved automatically, but you should save a copy in a secure place in case you need it later.
65+
66+
```sh
67+
docker compose logs panel | grep 'Generated app key:'
68+
```
69+
70+
### Installing
71+
72+
Open the installer in your browser at `APP_URL/installer` to finish setting up the panel.
73+
74+
:::note
75+
The first time the container starts after installing or updating, it will apply database migrations, which may take a few minutes. The panel will not be accessible during this process.
76+
:::
77+
78+
#### Sensible Driver Defaults:
79+
80+
* Cache Driver: Filesystem
81+
* Database Driver: SQLite
82+
* Queue Driver: Database
83+
* Session Driver: Filesystem
84+
85+
For other configuration, such as UI options, CAPTCHA, email, backups and OAuth, head to the settings menu in the admin panel.
86+
87+
### Stopping
88+
89+
The panel will automatically restart if the container crashes or the host restarts. If you need to non-destructively stop the panel for any reason, navigate back to the directory containing `compose.yml` and run:
90+
91+
```sh
92+
docker compose down
93+
```
94+
95+
### Uninstalling
96+
97+
To uninstall the panel, navigate to the directory containing `compose.yml` and run:
98+
99+
```sh
100+
docker compose down -v
101+
```
102+
103+
:::danger
104+
**This will permanently delete the panel and all associated data including the SQLite database and your encryption key.**
105+
:::
106+
107+
## Advanced Options
108+
109+
### Custom Caddyfile
110+
111+
The default Caddyfile will work for standard installations. If you need to edit the configuration of the integrated webserver, such as to place it behind a reverse proxy that terminates TLS, you can do so by bind-mounting a Caddyfile on the host to `/etc/caddy/Caddyfile` inside the container.
112+
113+
This example assumes there is a Caddyfile in the same directory as the `compose.yml` file.
114+
115+
```yml {15} title="compose.yml"
116+
services:
117+
panel:
118+
image: ghcr.io/pelican-dev/panel:latest
119+
restart: always
120+
networks:
121+
- default
122+
ports:
123+
- "80:80"
124+
- "443:443"
125+
extra_hosts:
126+
- "host.docker.internal:host-gateway"
127+
volumes:
128+
- pelican-data:/pelican-data
129+
- pelican-logs:/var/www/html/storage/logs
130+
- ./Caddyfile:/etc/caddy/Caddyfile
131+
environment:
132+
XDG_DATA_HOME: /pelican-data
133+
APP_URL: "http://localhost"
134+
ADMIN_EMAIL: "USEYOUROWNEMAILHERE@example.com"
135+
136+
volumes:
137+
pelican-data:
138+
pelican-logs:
139+
140+
networks:
141+
default:
142+
ipam:
143+
config:
144+
- subnet: 172.20.0.0/16
145+
```

‎docs/wings/install.mdx

Lines changed: 1 addition & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -45,48 +45,8 @@ Should that not work for some reason, or you're still unsure, you can also run t
4545
```sh
4646
sudo dmidecode -s system-manufacturer
4747
```
48-
4948
### Installing Docker
50-
51-
For a quick install of Docker CE, you can use the command below:
52-
53-
```sh
54-
curl -sSL https://get.docker.com/ | CHANNEL=stable sudo sh
55-
```
56-
57-
<Admonition type="info" title="Installing Docker CE">
58-
If the above command does not work, please reference the official Docker documentation for how to install Docker CE on your server.
59-
- [Docker CE Install Overview](https://docs.docker.com/engine/install/)
60-
</Admonition>
61-
62-
#### Start Docker on Boot
63-
64-
If you are on an operating system with systemd (Ubuntu 16+, Debian 8+, CentOS 7+) run the command below to have Docker start when you boot your machine.
65-
66-
```sh
67-
sudo systemctl enable --now docker
68-
```
69-
70-
### Enabling Swap
71-
72-
On most systems, Docker will be unable to setup swap space by default. You can confirm this by running `docker info` and looking for the output of `WARNING: No swap limit support` near the bottom.
73-
74-
Enabling swap is entirely optional, but we recommended doing it if you will be hosting for others and to prevent OOM errors.
75-
76-
To enable swap, open `/etc/default/grub` as a root user and find the line starting with `GRUB_CMDLINE_LINUX_DEFAULT`. Make
77-
sure the line includes `swapaccount=1` somewhere inside the double-quotes.
78-
79-
After that, run `sudo update-grub` followed by `sudo reboot` to restart the server and have swap enabled.
80-
Below is an example of what the line should look like, _do not copy this line verbatim. It often has additional OS-specific parameters._
81-
82-
```text
83-
GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1"
84-
```
85-
86-
<Admonition type="info" title="GRUB Configurations">
87-
Some Linux distros may ignore `GRUB_CMDLINE_LINUX_DEFAULT`.
88-
Therefore you might have to use `GRUB_CMDLINE_LINUX` instead should the above variable not work for you.
89-
</Admonition>
49+
Wings requires Docker CE. For instructions on installing and configuring Docker, see the [installation guide](/docs/guides/docker).
9050

9151
### Installing Wings
9252

‎sidebars.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ const sidebars: SidebarsConfig = {
3131
'panel/advanced/redis',
3232
'panel/advanced/mysql',
3333
'panel/advanced/artisan',
34+
'panel/advanced/docker',
3435
]
3536
}
3637
],
@@ -43,7 +44,7 @@ const sidebars: SidebarsConfig = {
4344
{
4445
type: 'category',
4546
label: 'Guides',
46-
items: ['guides/mounts', 'guides/ssl', 'guides/php-upgrade', 'guides/database-hosts', 'guides/uninstalling'],
47+
items: ['guides/docker', 'guides/mounts', 'guides/ssl', 'guides/php-upgrade', 'guides/database-hosts', 'guides/uninstalling'],
4748
},
4849
'troubleshooting',
4950
'comparison',

0 commit comments

Comments
 (0)