diff --git a/README.md b/README.md index 7e7f89fb..663d06d1 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Pelican Docs + Pelican docs are created with [Docusaurus](https://docusaurus.io). ## Building @@ -8,4 +9,4 @@ To test changes locally install the dependencies and run the server using pnpm. ```shell pnpm i pnpm run start -``` \ No newline at end of file +``` diff --git a/docs/about.mdx b/docs/about.mdx deleted file mode 100644 index 4b28d022..00000000 --- a/docs/about.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -id: about ---- - -# The Team & Pelican - -### Core Team - -| Name | Discord | Role | -|--------------------------------------------------------|-----------------|-----------------------------| -| [Lance Pioch](https://github.com/lancepioch) | `shadowlancer` | Project Lead & Fullstack Dev| -| [Michael Parker](https://github.com/parkervcp) | `parkervcp` | Egg/ Docker Maintainer | -| [Charles Morgan](https://github.com/notAreYouScared) | `areyouscared` | Fullstack Dev | -| [Alex 'Scai' Vlad](https://github.com/alexevladgabriel)| `.scai` | Fullstack Dev | -| [Boy132](https://github.com/boy132) | `boy132` | Fullstack Dev | -| [Martin Oscar](https://github.com/RMartinOscar) | `rmartinoscar` | Fullstack Dev | - -Core members of Pelican have a light blue username in Discord. - -### Community Staff - -| Name | Discord | Role | -|------------------------------------------------|---------------|---------------| -| [Trixter](https://github.com/TrixterTheTux) | `trixter` | Moderator | -| [Quinten](https://github.com/QuintenQVD0) | `quintenqvd` | Egg Maintainer| -| [Red-Thirten](https://github.com/redthirten) | `red_thirten` | Egg Maintainer| - -Community Staff have a darker blue username in Discord. - -## License - -Pelican® Copyright © 2024 - -Code released under AGPLv3 diff --git a/docs/comparison.mdx b/docs/comparison.mdx index eafd8d45..75139bdc 100644 --- a/docs/comparison.mdx +++ b/docs/comparison.mdx @@ -1,18 +1,20 @@ --- -id: comparison +pagination_prev: null +pagination_next: null --- -import Admonition from '@theme/Admonition'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Comparison -Pelican is a fork of [Pterodactyl](https://pterodactyl.io). However, Pelican has many Improvements over it now! +Pelican is a fork of [Pterodactyl](https://pterodactyl.io). However, Pelican has many improvements over it now! - +:::info Want to see these changes in action? Check out our [Demo](https://demo.pelican.dev)! - +::: + +## Roadmap @@ -93,24 +95,26 @@ Pelican is a fork of [Pterodactyl](https://pterodactyl.io). However, Pelican has -## Comparison with our competitors. -| | Pelican | Pterodactyl | PufferPanel | Crafty Controller | Multicraft | TCAdmin | AMP | -|--------------------------|-----------|-------------|-------------|-----------------------|----------------|---------|----------------| -| File manager | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| Scheduled Tasks | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | -| Free and Open Source | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | -| Multilingual | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | -| Database Management | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | -| OAuth | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | -| Webhooks | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | -| Roles & Permissions | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | -| Announcements | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | -| Themes | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | -| Plugins | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | -| Self update | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | -| Captcha Login | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | -| Remote Backups | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | +## Comparison with other software + +| | Pelican | Pterodactyl | PufferPanel | Crafty Controller | Multicraft | TCAdmin | AMP | +| -------------------- | ------- | ----------- | ----------- | ----------------- | ---------- | ------- | --- | +| Free and Open Source | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | +| Multilingual | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Plugins | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Themes | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | +| File manager | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Scheduled Tasks | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | +| Database Management | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | +| OAuth | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | +| Webhooks | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | +| Roles & Permissions | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| Captcha Login | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | +| Remote Backups | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | +| Self update | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Announcements | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | + +#### Features information -### Features information. -- Plugins can add any features that Pelican doesn't have by default. -- These values are not constantly updated, and competitors may have implemented some of the features marked with a cross in their latest version. +- Plugins can add any feature that Pelican doesn't have by default. +- These values are not constantly updated and the other software may have implemented some of the features marked with a cross in their latest version. diff --git a/docs/glossary.mdx b/docs/glossary.mdx index ae54480d..9865c514 100644 --- a/docs/glossary.mdx +++ b/docs/glossary.mdx @@ -1,11 +1,10 @@ --- -id: glossary +pagination_prev: null +pagination_next: null --- # Glossary -### What is ...? - **Panel** — web application that interfaces with Wings and lets you control your Servers. **Wings** — application that gives you secure control of your Servers via your Panel. @@ -25,19 +24,6 @@ id: glossary **Yolk** — curated collection of (core) Docker Images that can be used with Pelican's Eggs. -## Basic Example Setup Diagram - -```mermaid -flowchart TD - A(Pelican Panel) - A --> B1(Basement Server) - A --> B2(Rented Server) - B1 --> W1(Wings) - B2 --> W2(Wings) - W2 ---> C5(Palworld) - W2 ---> C6(Discord Bot) - W1 ---> C7(FTB Minecraft) - W1 ---> C8(Factorio) - W1 ---> C9(GTA FiveM) - W1 ---> C4(Project Zomboid) -``` +#### Basic Example Setup Diagram + +![Example banner](/img/docs/example_setup.png) diff --git a/docs/guides/change-panel-domain.mdx b/docs/guides/change-panel-domain.mdx index c9c3b353..55ce32d1 100644 --- a/docs/guides/change-panel-domain.mdx +++ b/docs/guides/change-panel-domain.mdx @@ -1,10 +1,11 @@ -import Admonition from '@theme/Admonition'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Change Panel Domain -## Webserver & Panel +A brief guide on how to change the Panel domain. + +## Web server & Panel First you need to modify the server name in your web server config. @@ -15,9 +16,9 @@ First you need to modify the server name in your web server config. # Search for "server_name" ``` - - If you're using HTTPS, remember to also change the SSL paths in the config file to match your new domain and [generate a new certificate](./ssl). - + :::info[Using HTTPS?] + If you're using HTTPS, remember to also change the SSL paths in the config file to match your new domain and [generate a new certificate](ssl). + ::: ```sh @@ -25,9 +26,9 @@ First you need to modify the server name in your web server config. # Search for "ServerName" ``` - - If you're using HTTPS, remember to also change the SSL paths in the config file to match your new domain and [generate a new certificate](./ssl). - + :::info[Using HTTPS?] + If you're using HTTPS, remember to also change the SSL paths in the config file to match your new domain and [generate a new certificate](ssl). + ::: ```sh @@ -38,7 +39,7 @@ First you need to modify the server name in your web server config. Next, modify the `APP_URL` in the `.env` file located at `/var/www/pelican` by typing `sudo nano /var/www/pelican/.env`. -Finally, restart your webserver to apply the changes. +Finally, restart your web server to apply the changes. diff --git a/docs/guides/database-hosts.mdx b/docs/guides/database-hosts.mdx index 2aa6a459..f35ff163 100644 --- a/docs/guides/database-hosts.mdx +++ b/docs/guides/database-hosts.mdx @@ -1,5 +1,3 @@ -import Admonition from '@theme/Admonition'; - # Database Hosts Database hosts allow to create per-server databases on the given host. @@ -35,15 +33,15 @@ Open `my.cnf`, add text below to the bottom of the file and save it: bind-address=0.0.0.0 ``` -Restart MySQL/ MariaDB to apply these changes. This will override the default MySQL configuration, which by default will only accept requests from localhost. Updating this will allow connections on all interfaces, and thus, external connections. Make sure to allow the MySQL port (default 3306) in your firewall. +Restart MySQL/MariaDB to apply these changes. This will override the default MySQL configuration, which by default will only accept requests from localhost. Updating this will allow connections on all interfaces, and thus, external connections. Make sure to allow the MySQL port (default 3306) in your firewall. ## Panel Configuration In the admin area of the panel, go to "Databases" and click the "New Database Host" button. - +:::tip Users will later see the host as their database endpoint. Therefore, you should set it to a public ip or FQDN and not to `localhost` for example. - +::: Hit "Create" and if everything was entered correctly you should be redirected to the database host list and see your new database host. diff --git a/docs/guides/disk-quotas/ext4-xfs.mdx b/docs/guides/disk-quotas/ext4-xfs.mdx index 2683784b..ae511237 100644 --- a/docs/guides/disk-quotas/ext4-xfs.mdx +++ b/docs/guides/disk-quotas/ext4-xfs.mdx @@ -1,7 +1,5 @@ -import Admonition from '@theme/Admonition'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import Link from '@docusaurus/Link'; # EXT4 and XFS @@ -9,21 +7,22 @@ This page covers disk quota management for EXT4/XFS. Both EXT4 and XFS use the built-in quota management services in linux. - - Please read About Quotas before continuing - +:::warning + Please read [About Quotas](./) before continuing +::: ## Configure Filesystem + How to format and mount a device for use with quotas
I understand the risks and Pelican is not Liable for anything that breaks - +:::warning Enabling quotas for `/` is difficult, as it requires booting a live disk to change. We do not recommended this! - +::: These examples use the following: `/dev/sdb` as the device formatted as EXT4 enabling only project quotas. @@ -41,9 +40,9 @@ These examples use the following: mkfs.ext4 -O quota -E quotatype=prjquota /dev/sdb ``` - + :::warning You need to update fstab so the disk mounts automatically on boot with quotas enabled. - + ::: ## Add to fstab ### get device UUID @@ -63,11 +62,11 @@ These examples use the following: ``` For more information on fstab check the [Arch Linux fstab docs](https://wiki.archlinux.org/title/Fstab) - + :::warning Depending on the OS you may need to refresh services to be able to mount the partition after updating `fstab`. It is often easier to reboot and have the disk mount on boot. - + ::: ## Update existing partition @@ -91,9 +90,9 @@ These examples use the following: ``` ## Enable quotas - + :::warning This can only be ran on an unmounted disk - + ::: `tune2fs` is used to adjust tunable file system parameters for EXT filesystems * The `Q` flag is to manage quotas - `prjquota` is to enable project quotas @@ -114,32 +113,35 @@ These examples use the following: ``` For more information on fstab check the [Arch Linux fstab docs](https://wiki.archlinux.org/title/Fstab) - + :::warning Depending on the OS you may need to refresh services to be able to mount the partition after updating `fstab`. It is often easier to reboot and have the disk mount on boot. - + :::
## Advanced EXT4 Quota Management - + +:::danger The following section is for manual management of quotas. - +:::
I understand - +:::danger You should never need to go here, this is your last warning. - +:::
I agree and Pelican is not Liable for anything that breaks ## Manually Manage Quotas + Limits for the servers are managed on a "project" level so they can be assigned per-directory. ### Add A New Project + To add a new project 2 files must be edited. First is the `projid` file which is formatted where each line is in the `project_name:project_id` format as seen below @@ -157,6 +159,7 @@ Second is the `projects` file which is formatted where each line is in the `proj ``` ### Set directory attributes + The project attribute must be set on the directory to track quota usage. The `chattr` command changes attribute for files and directories. @@ -198,6 +201,7 @@ setquota -P 235844d3-9258-4846-bb04-bcff209ccf9a 0 10G 0 0 /var/lib/pelican/volu ``` ### get quota stats + The `repquota` command will generate a report on the quotas for the specified device or mount path * The `P` flag will break down the report by project. - In this case it should be the server UUID that is the project name @@ -221,6 +225,6 @@ cdb26bbb-963d-44b1-8353-360243032b1 -- 2G 0G 2G 1g
- +:::note TODO: Add documentation specifically for XFS - \ No newline at end of file +::: \ No newline at end of file diff --git a/docs/guides/disk-quotas/about.mdx b/docs/guides/disk-quotas/index.mdx similarity index 62% rename from docs/guides/disk-quotas/about.mdx rename to docs/guides/disk-quotas/index.mdx index 0ac5a804..64e79a6f 100644 --- a/docs/guides/disk-quotas/about.mdx +++ b/docs/guides/disk-quotas/index.mdx @@ -1,29 +1,27 @@ -import Admonition from '@theme/Admonition'; -import Link from '@docusaurus/Link'; +# Quotas -# About Quotas - - +:::tip As called out in the Wings install docs, it is always recommended to keep the server files on a separate partition. - +::: ## There are a lot of notices here for a reason! - +:::danger Support for disk quotas is still being worked on! - +::: - +:::warning These are advanced configurations meant for hosts but "should" work for individuals as well. - +::: - +:::warning Depending on the filesystem Quotas can be difficult to enable for the `/` mount, which requires booting a live disk to change. - +::: - +:::info You can either make a new mount with quotas enabled or enable quotas on an existing partition. - +::: ## Filesystem-specific docs -EXT4/XFS \ No newline at end of file + +- [EXT4/XFS](ext4-xfs) \ No newline at end of file diff --git a/docs/guides/docker.mdx b/docs/guides/docker.mdx deleted file mode 100644 index 5e707565..00000000 --- a/docs/guides/docker.mdx +++ /dev/null @@ -1,42 +0,0 @@ -import Admonition from '@theme/Admonition'; - -# Installing Docker - -For a quick install of Docker CE, you can use the command below: - -```sh -curl -sSL https://get.docker.com/ | CHANNEL=stable sudo sh -``` - - - 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. - - -## Start Docker on Boot - -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. - -```sh -sudo systemctl enable --now docker -``` - -## Enabling Swap - -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. - -Enabling swap is entirely optional, but we recommended doing it if you will be hosting for others and to prevent OOM errors. - -To enable swap, open `/etc/default/grub` as a root user and find the line starting with `GRUB_CMDLINE_LINUX_DEFAULT`. Make -sure the line includes `swapaccount=1` somewhere inside the double-quotes. - -After that, run `sudo update-grub` followed by `sudo reboot` to restart the server and have swap enabled. -Below is an example of what the line should look like, _do not copy this line verbatim. It often has additional OS-specific parameters._ - -```text -GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1" -``` - - - Some Linux distros may ignore `GRUB_CMDLINE_LINUX_DEFAULT`. - Therefore you might have to use `GRUB_CMDLINE_LINUX` instead should the above variable not work for you. - \ No newline at end of file diff --git a/docs/eggs/creating-a-custom-egg.mdx b/docs/guides/eggs/creating-a-custom-egg.mdx similarity index 97% rename from docs/eggs/creating-a-custom-egg.mdx rename to docs/guides/eggs/creating-a-custom-egg.mdx index 6076c583..51b6f05e 100644 --- a/docs/eggs/creating-a-custom-egg.mdx +++ b/docs/guides/eggs/creating-a-custom-egg.mdx @@ -1,5 +1,7 @@ # Creating a Custom Egg +A guide on how to create a custom Egg. + ## Create New Egg Navigate to the Admin Panel and click the eggs option in the sidebar then select `New Egg` button. @@ -7,24 +9,32 @@ Navigate to the Admin Panel and click the eggs option in the sidebar then select You will be taken to a new egg configuration page which is where most of the configuration happens. ### Name + This is the name of your egg. ### Author + This is the original creator's email. ### Description + This is the description of your egg and what is needed to run it. ### Startup Commands + Here you can assign multiple startup commands to run your server. Example below: + ```bash java -Xms128M -XX:MaxRAMPercentage=95.0 -Dterminal.jline=false -Dterminal.ansi=true -jar {{SERVER_JARFILE}} ``` + ### File Denylist + Here you can specify a list of files that the end user is not allowed to edit. ### Features (Egg Features) + Egg features can do different things when specified. Example below: | Tag | Description | | ------------------------- | ------------------------------------------- | @@ -34,12 +44,15 @@ Egg features can do different things when specified. Example below: | steam_disk_space | Sets a limit to enable an "out of disk space" Popup if the host system is out of disk space | ### Tags + The tag system allows you to group eggs together by type. This is the successor to nests. ### Update URL + This can be specified so that users who use your egg can update the egg without having to look around for where the egg is hosted. ### Docker Images (Yolks) + Every egg has a Docker image or Yolk as they are referred to. Images can be custom-made, and you can learn how to create them in the "Creating a Custom Yolk" guide or you can use the pre-made ones found here [Yolk Repo](https://github.com/pelican-eggs/yolks). They have two fields that need to be defined: the name of the image and the URL where the image is hosted. :::info @@ -166,13 +179,14 @@ java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}} ``` :::note -Variable syntax depends on the context: -**Startup commands**: Use `{{VAR_NAME}}` (e.g., `{{SERVER_MEMORY}}`) -**Configuration file parsers**: Use `{{server.environment.VAR_NAME}}` or `{{server.allocations.default.port}}` -**Install scripts and shell environments**: Use `${VAR_NAME}` + Variable syntax depends on the context: + **Startup commands**: Use `{{VAR_NAME}}` (e.g., `{{SERVER_MEMORY}}`) + **Configuration file parsers**: Use `{{server.environment.VAR_NAME}}` or `{{server.allocations.default.port}}` + **Install scripts and shell environments**: Use `${VAR_NAME}` ::: **In Install Scripts:** + ```bash #!/bin/bash cd /mnt/server diff --git a/docs/eggs/creating-a-custom-yolk.mdx b/docs/guides/eggs/creating-a-custom-yolk.mdx similarity index 99% rename from docs/eggs/creating-a-custom-yolk.mdx rename to docs/guides/eggs/creating-a-custom-yolk.mdx index c18648d4..bb638311 100644 --- a/docs/eggs/creating-a-custom-yolk.mdx +++ b/docs/guides/eggs/creating-a-custom-yolk.mdx @@ -1,6 +1,7 @@ - # Creating a Custom Yolk +A guide on how to create a custom Yolk. (Docker image for Pelican) + :::warning This tutorial uses examples from our [`ghcr.io/pelican-eggs/yolks:java_8`](https://github.com/pelican-eggs/yolks) docker image, which can be found on GitHub. This tutorial also assumes some knowledge of [Docker](https://docker.io/), we suggest reading up if this all looks foreign to you. ::: diff --git a/docs/guides/mounts.mdx b/docs/guides/mounts.mdx index 965a9d95..ce9575f5 100644 --- a/docs/guides/mounts.mdx +++ b/docs/guides/mounts.mdx @@ -1,8 +1,6 @@ -import Admonition from '@theme/Admonition'; - # Using Mounts -Mounts is a feature that allows administrators to mount other directories from the host file-system into a Server's container. +Mounts allow administrators to mount other directories from the host file-system into a Server's container. ## Wings Configuration @@ -23,10 +21,10 @@ You have to restart Wings to apply new changes to your Wings config. You have to configure mounts in admin Panel in order to use them with your servers. They consist of a source pad on the node and a target path where it will be mounted in the container. - +:::warning By default Mounts cannot target `/home/container` or any of its subdirectory, you can allow it by setting `BlockBaseDirMount` to `false` in the Wings configuration. You cannot cross-mount servers such as Server A's directory into Server B. - +::: ### Creating a Mount @@ -41,9 +39,9 @@ You have to configure mounts in admin Panel in order to use them with your serve - **User Mountable**: Whether to allow users to self mount this mount. 4. After creating the mount, you are required to add both **Eggs** and **Nodes** that this mount may be used on. - +:::warning All servers using the same mounts will **only** share their contents when they are on the same node. Mounts are not synchronized between nodes. - +::: ### Assigning a Mount to a Server @@ -54,9 +52,9 @@ You have to configure mounts in admin Panel in order to use them with your serve The files of the mount should become available in the target path in the container. You can temporarily change your server startup command to `ls `, which should output the contents of the mount if configured correctly. - +:::tip Mounts do not appear in the Panel's file manager, nor are they accessible via SFTP. However, the server itself will be able to see and use the mounts. - +::: ### Example Mount diff --git a/docs/guides/php-upgrade.mdx b/docs/guides/php-upgrade.mdx index 00a7ec3a..186b6fb5 100644 --- a/docs/guides/php-upgrade.mdx +++ b/docs/guides/php-upgrade.mdx @@ -1,14 +1,11 @@ ---- -id: php-upgrade ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Upgrading PHP -This documentation includes instructions for upgrading your system to the latest version of PHP. Please reference the -table below to check what PHP version you need for your version of Pelican. +A brief guide on how to upgrade PHP to the latest supported version. + +Please reference the table below to check what PHP version you need for your version of Pelican. | Panel Version | PHP Version | |---------------|--------------------| @@ -31,7 +28,7 @@ sudo apt -y purge php* sudo apt -y install php8.5 php8.5-{gd,mysql,mbstring,bcmath,xml,curl,zip,intl,sqlite3,fpm} ``` -## Webserver Configuration +## Web server Configuration diff --git a/docs/guides/ssl.mdx b/docs/guides/ssl.mdx index d52e2bec..0371c160 100644 --- a/docs/guides/ssl.mdx +++ b/docs/guides/ssl.mdx @@ -1,286 +1,129 @@ -import Admonition from '@theme/Admonition'; +--- +pagination_prev: null +pagination_next: null +--- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - # Creating SSL Certificates -These tutorials briefly cover creating a new SSL certificates for your panel and/or wings. +A brief guide on how to create SSL certificates for your Panel and/or Wings using Certbot. + +## Install Certbot + +To begin, we will install certbot, a simple script that automatically renews our certificates and allows much easier creation of them. +The command below is for Ubuntu distributions, but you can always check [Certbot's official site](https://certbot.eff.org/) for installation instructions. +We have also included a command below to install certbot's Nginx/Apache plugin so you won't have to stop your web server. - - - This way is the most recommended and should work in 98% of setups. - - To begin, we will install certbot, a simple script that automatically renews our certificates and allows much easier creation of them. - The command below is for Ubuntu distributions, but you can always check [Certbot's official site](https://certbot.eff.org/) for installation instructions. - We have also included a command below to install certbot's Nginx/Apache plugin so you won't have to stop your webserver. - - - - ```sh - sudo apt install -y python3-certbot-nginx - ``` - - - ```sh - sudo apt install -y python3-certbot-apache - ``` - - - ```sh - sudo apt install -y certbot - ``` - - + + ```sh + sudo apt install -y python3-certbot-nginx + ``` + + + ```sh + sudo apt install -y python3-certbot-apache + ``` + + + ```sh + sudo apt install -y certbot + ``` + + - ### Creating a Certificate +## Creating a Certificate - After installing certbot, we need to generate a certificate. There are a couple of ways to do that, but the easiest - is to use the web server-specific certbot plugin you just installed. - - - For Wings-only machines that don't need a web server, use the standalone or DNS method of the certbot as you don't need a web server for it. - +After installing certbot, we need to generate a certificate. There are a couple of ways to do that, but the easiest +is to use the web server-specific certbot plugin you just installed. - Then, in the command below, you should replace `example.com` with the domain you would like to generate a certificate - for. When you have multiple domains you would like certificates for, simply add more `-d anotherdomain.com` flags to the - command. You can also look into generating a wildcard certificate but that is not covered in this tutorial. +:::info + For Wings-only machines that don't need a web server, use the standalone or DNS method of the certbot as you don't need a web server for it. +::: - When you are using certbot's Nginx/Apache plugin, you won't need to restart your webserver to have the certificate - applied assuming that you've already configured the webservers to use SSL as instructed in the [web server configuration step](../panel/webserver-config). - - ### HTTP challenge +Then, in the command below, you should replace `example.com` with the domain you would like to generate a certificate +for. When you have multiple domains you would like certificates for, simply add more `-d anotherdomain.com` flags to the +command. You can also look into generating a wildcard certificate but that is not covered in this tutorial. +When you are using certbot's Nginx/Apache plugin, you won't need to restart your web server to have the certificate +applied assuming that you've already configured the web servers to use SSL as instructed in the [web server configuration step](../panel/install/standalone#web-server-configuration). + + + HTTP challenge requires you to expose port 80 for the challenge verification. - + ```sh certbot certonly --nginx -d example.com ``` - + ```sh certbot certonly --apache -d example.com ``` - + ```sh certbot certonly --standalone -d example.com ``` - - ### DNS challenge - + + DNS challenge requires you to create a new TXT DNS record to verify domain ownership, instead of having to expose port 80. The instructions are displayed when you run the certbot command below. ```sh certbot -d example.com --manual --preferred-challenges dns certonly ``` - - ### Auto Renewal - - You'll also probably want to configure the automatic renewal of certificates to prevent unexpected certificate expirations. - You can open crontab with `sudo crontab -e` and add the line from below to the bottom of it for attempting renewal every day at 23 (11 PM). - - Deploy hook would restart the Nginx service to apply a new certificate when it's renewed successfully. Change `nginx` in the restart command to suit your own needs, such as to `apache` or `wings`. - - - For advanced users, we suggest installing and using [acme.sh](https://acme.sh) - which provides more options, and is much more powerful than certbot. - - - ```text - 0 23 * * * certbot renew --quiet --deploy-hook "systemctl restart nginx" - ``` - - ### Troubleshooting - - If you get an `Insecure Connection` or SSL/TLS related error when trying to access your panel or wings, the certificate has likely expired. - This can be easily fixed by renewing the SSL certificate, although using the command `certbot renew` might not do the job if port 80 is in use, as it'll return errors like: `Error: Attempting to renew cert (domain) from /etc/letsencrypt/renew/domain.conf produced an unexpected error`. - - This will happen especially if you're running Nginx instead of Apache. The solution for this is to use Nginx or Apache plugins with `--nginx` and `--apache`. Alternatively, you can stop Nginx, then renew the certificate, finally restart Nginx. Replace `nginx` with your own web server or with `wings` should you be renewing the certificate for Wings. - - Stop Nginx: - - ```sh - systemctl stop nginx - ``` - - Renew the certificate: - - ```sh - certbot renew - ``` - - Once the process has completed, you can restart Nginx: - - ```sh - systemctl start nginx - ``` - - You may also need to restart Wings as not every service is able to automatically apply an updated certificate: - - ```sh - systemctl restart wings - ``` + - - - This is for advanced users, whose server systems do not have access to port 80. - The command below is for Ubuntu distributions and CloudFlare API (you may google for other APIs for other DNS providers), - but you can always check [acme.sh's official site](https://github.com/Neilpang/acme.sh) for installation instructions. - - Make sure you read both instructions, as some people may have moved to CloudFlare's [new authorization system](https://blog.cloudflare.com/permissions-best-practices) (Modern), but other's [have not](https://community.cloudflare.com/t/cannot-add-new-member-error-1005/421516) (Legacy). - - - ```sh - curl https://get.acme.sh | sh - ``` - - - - ### Obtaining CloudFlare API Key (Legacy) - - After installing acme.sh, we need to fetch a CloudFlare API key. - On Cloudfare's website, select your domain, then on the right side, copy your "Zone ID" and "Account ID". - Click on "Get your API token", click on "Create Token" > select the template "Edit zone DNS" > select the scope of "Zone Resources" - Click on "Continue to summary", copy your token. - - ### Creating a Certificate - - Since the configuration file is based on Certbot, we need to create the folder manually. - - ```sh - sudo mkdir -p /etc/letsencrypt/live/example.com - ``` - - After installing acme.sh and obtaining CloudFlare API key, we need to then generate a certificate. First input the CloudFlare API credentials. - - ```sh - export CF_Token="Your_CloudFlare_API_Key" - export CF_Account_ID="Your_CloudFlare_Account_ID" - export CF_Zone_ID="Your_CloudFlare_Zone_ID" - ``` - - - - ### Obtaining CloudFlare API Key (Modern) - - After installing acme.sh, we need to fetch a CloudFlare API key. - - Cloudfare's website, click on your profile on the top right. - - Go to "My Profile" --> "[API Tokens](https://dash.cloudflare.com/profile/api-tokens)". - - Click "Create Token" and use the "Edit zone DNS" template. - - Then once on the next page, goto "Zone Resources" and "Include" - "Specific Zone" - (Select the domain you want to use). - - Continue to the summery. - - Confirm you'd like to create the token. - - ### Creating a Certificate - - Since the configuration file is based on Certbot, we need to create the folder manually. - - ```sh - sudo mkdir -p /etc/letsencrypt/live/example.com - ``` - - After installing acme.sh and obtaining CloudFlare API key, we need to then generate a certificate. First input the CloudFlare API credentials. - - ```sh - export CF_Key="Your_CloudFlare_API_Key" - export CF_Email="Your_CloudFlare_Email" - ``` - - - - - - - This is for advanced users, who are running Cloudflare in proxy mode or do not have access to port `80`. - - - ### Installing Caddy with Cloudflare DNS plugin - - Caddy does not come by default with Cloudflare DNS plugin, you need to install it yourself. - - There are two main methods: - - 1. Using `xcaddy` - CLI tool to build your own Caddy build - 2. Downloading prebuilt binary from [Caddy's download page](https://caddyserver.com/download). - 3. Using Ansible to download and install Caddy with plugins. See [caddy-ansible](https://github.com/caddy-ansible/caddy-ansible) - - #### Build Caddy using `xcaddy` on your server - - Please refer to [Caddy docs on building Caddy](https://caddyserver.com/docs/build#xcaddy). - - ### Obtaining CloudFlare API Token - - After installing acme.sh, we need to fetch a CloudFlare API key. Please make sure that a DNS record (A or CNAME record) is pointing to your target node, and set the cloud to grey (bypassing CloudFlare proxy). Then go to My Profile > API keys and on Global API Key subtab, click on "view", enter your CloudFlare password, and copy the API key to clipboard. +## Auto Renewal - After install Caddy with Cloudflare DNS plugin, we need to fetch a Cloudflare API token. - Please make sure that a DNS record (A or CNAME record) is pointing at your target node. - Then go to My Profile > API Tokens and on API Tokens click "Create Token". - Create API Token > API token templates, at the end of line with "Edit zone DNS", click "Use template". Under **Zone Resources**, select your DNS zone for which you wish to create the API token, click "Continue to summary". - Review the API token summary and click "Create Token". Finally copy the API token to clipboard. +You'll also probably want to configure the automatic renewal of certificates to prevent unexpected certificate expirations. +You can open crontab with `sudo crontab -e` and add the line from below to the bottom of it for attempting renewal every day at 23 (11 PM). - ### Reconfiguring Caddy to use Cloudflare DNS for obtaining certificates +Deploy hook would restart the Nginx service to apply a new certificate when it's renewed successfully. Change `nginx` in the restart command to suit your own needs, such as to `apache` or `wings`. - Create an environment variable file (like `.env`), keep in mind that this file contains secrets and should not be accessed by public. +:::info + For advanced users, we suggest installing and using [acme.sh](https://acme.sh) + which provides more options, and is much more powerful than certbot. +::: - We recommend that you create the secret file in the following location: `/etc/caddy/.secrets.env`. +```text +0 23 * * * certbot renew --quiet --deploy-hook "systemctl restart nginx" +``` - ```sh - CLOUDFLARE_API_TOKEN= - ``` +## Troubleshooting - For security reasons, we recommend setting permissions to `0600` (only owner can read or write to the file). +If you get an `Insecure Connection` or SSL/TLS-related error when trying to access your panel or wings, the certificate has likely expired. +This can be easily fixed by renewing the SSL certificate, although using the command `certbot renew` might not do the job if port 80 is in use, as it'll return errors like: `Error: Attempting to renew cert (domain) from /etc/letsencrypt/renew/domain.conf produced an unexpected error`. - ```sh - # Set ownership of the `.secrets.env` file to `caddy` system user - sudo chown caddy:caddy /etc/caddy/.secrets.env +This will happen especially if you're running Nginx instead of Apache. The solution for this is to use Nginx or Apache plugins with `--nginx` and `--apache`. Alternatively, you can stop Nginx, then renew the certificate, finally restart Nginx. Replace `nginx` with your own web server or with `wings` should you be renewing the certificate for Wings. - # Set read-write permissions only to owner - the `caddy` system user - sudo chmod 0600 /etc/caddy/.secrets.env - ``` +Stop Nginx: - Modify the systemd unit file, to load environment variables from file (add `--envfile /etc/caddy/.secrets.env` flag to `ExecStart`), the default systemd unit file location is `/etc/systemd/system/caddy.service`: +```sh +systemctl stop nginx +``` - ```unit {12} - [Unit] - Description=Caddy - Documentation=https://caddyserver.com/docs/ - After=network.target network-online.target - Requires=network-online.target +Renew the certificate: - [Service] - Type=notify - User=caddy - Group=caddy - ExecStart=/usr/bin/caddy run --environ --envfile /etc/caddy/.secrets.env --config /etc/caddy/Caddyfile - ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile - TimeoutStopSec=5s - LimitNOFILE=1048576 - LimitNPROC=512 - PrivateTmp=true - ProtectSystem=full - AmbientCapabilities=CAP_NET_BIND_SERVICE +```sh +certbot renew +``` - [Install] - WantedBy=multi-user.target - ``` +Once the process has completed, you can restart Nginx: - You can add a `tls` block to your `Caddyfile`, under the `` block of your panel configuration, the Caddy config file location is `/etc/caddy/Caddyfile`: +```sh +systemctl start nginx +``` - ```caddyfile {5-7} - { - # ...s +You may also need to restart Wings as not every service can automatically apply an updated certificate: - tls { - dns cloudflare {env.CLOUDFLARE_API_TOKEN} - } - } - ``` - - +```sh +systemctl restart wings +``` \ No newline at end of file diff --git a/docs/guides/uninstalling.mdx b/docs/guides/uninstalling.mdx index 1148e914..7e18f614 100644 --- a/docs/guides/uninstalling.mdx +++ b/docs/guides/uninstalling.mdx @@ -1,14 +1,15 @@ -import Admonition from '@theme/Admonition'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Uninstalling -This guide will show you how to uninstall the Pelican Panel and Wings. Note that the uninstallation of dependency services is not covered here. +This guide will show you how to uninstall the Pelican Panel and Wings. - +Note that the uninstallation of dependency services is not covered here. + +:::danger **You will lose all data and this action is irreversible!** - +::: ## Panel @@ -20,9 +21,9 @@ First, run the following command to delete all panel files. sudo rm -rf /var/www/pelican ``` -### Webserver config +### Web server config -Next, remove the Pelican webserver config. +Next, remove the Pelican web server config. @@ -61,7 +62,7 @@ sudo rm /etc/systemd/system/pelican-queue.service ### (Optional) Panel database -If you used MySQL/ MariaDB and also want to remove the panel database, run the following commands: +If you used MySQL/MariaDB and also want to remove the panel database, run the following commands: ```sh mysql -u root -p diff --git a/docs/index.mdx b/docs/index.mdx index c0a496ed..58f429de 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,47 +1,76 @@ --- id: welcome +pagination_prev: null +pagination_next: null --- -import Admonition from '@theme/Admonition'; +# Welcome -# Welcome to Pelican! +## What is Pelican? -### Who is Pelican? -In the realm of technology and hosting services, bold pioneers left the constraints of Pterodactyl to forge their own path. +Pelican is an open-source game server management tool built upon [Pterodactyl](https://pterodactyl.io), paired with Wings, which runs the game servers in isolated Docker containers for maximum separation and stability. -United by a shared vision and a relentless pursuit of excellence, they came together to form the heart and soul of **Pelican**—a beacon of innovation and reliability, defined not only by its technological prowess but also by its unwavering dedication to customer satisfaction. +:::note[Reporting Security Issues] + If you notice anything that raises a concern, please create a [Github security advisory](https://github.com/pelican-dev/panel/security/advisories/new) or reach out directly to **team@pelican.dev** + For security reasons, we ask that you handle security disclosures responsibly and **avoid posting them as GitHub issues/discussions.** +::: -With innovation as their compass and collaboration as their strength, Pelican soars to new heights, shaping the future of server management with each triumphant flight. +:::info + Want to see these Pelican in action? Check out our [Demo](https://demo.pelican.dev)! +::: -### Core Team +## Installation -| Name | Discord | Role | -|--------------------------------------------------------|-----------------|-----------------------------| -| [Lance Pioch](https://github.com/lancepioch) | `shadowlancer` | Project Lead & Fullstack Dev| -| [Michael Parker](https://github.com/parkervcp) | `parkervcp` | Egg / Docker Maintainer | -| [Charles Morgan](https://github.com/notAreYouScared) | `areyouscared` | Fullstack Dev | -| [Alex 'Scai' Vlad](https://github.com/alexevladgabriel)| `.scai` | Fullstack Dev | -| [Boy132](https://github.com/boy132) | `boy132` | Fullstack Dev | -| [Martin Oscar](https://github.com/RMartinOscar) | `rmartinoscar` | Fullstack Dev | +Pelican consists of two main components: the **Panel** and **Wings**. -Core members of Pelican have a light blue username in Discord. +The Panel is a [Laravel](https://laravel.com) web application that serves as the web interface for users. +Wings is the backend service installed on one or more node machines and acts as the interface between [Docker](https://docker.com) and the Panel. -### Community Staff +:::warning + Pelican is currently in **Beta**! Some things might change/break between beta versions! +::: + +### First steps + +:::info[What is...?] + Not sure what a specific term means? Check out our [Glossary](/docs/glossary)! +::: + +First you will need to install the Panel. You can choose between two installation methods: + +1. [Standalone](panel/install/standalone) - run the Pelican Panel directly on a web server. +2. [Dockerized](panel/install/dockerized) - run the Pelican Panel inside a docker container. + +### Node setup -| Name | Discord | Role | -|------------------------------------------------|---------------|---------------| -| [Trixter](https://github.com/TrixterTheTux) | `trixter` | Moderator | -| [Quinten](https://github.com/QuintenQVD0) | `quintenqvd` | Egg Maintainer| -| [Red-Thirten](https://github.com/redthirten) | `red_thirten` | Egg Maintainer| +After you set up your Panel, you will need to create some Nodes. To do that, install and configure the Wings daemon on the same machine as the Panel or on a separate machine. -Community Staff have a darker blue username in Discord. -### What is Pelican? -Pelican is an open-source game server management tool built upon Pterodactyl, paired with Wings, which runs the game servers in isolated Docker containers for maximum separation and stability. +Similar to the Panel installation you can choose between two installation methods: -### Open Source! -Pelican is open-source, allowing users to browse the code, contribute improvements, and help to identify bugs and security issues. +1. [Standalone](wings/install/standalone) - run the Wings Daemon directly on a linux server. +2. [Dockerized](wings/install/dockerized) - run the Wings Daemon inside a docker container. + +:::note + A Panel can have multiple Nodes but a Node is always tied to just one Panel. +::: + +## The Team + +### Core Team + +| Name | Discord | +|--------------------------------------------------------|-----------------| +| [Lance Pioch](https://github.com/lancepioch) | `shadowlancer` | +| [Michael Parker](https://github.com/parkervcp) | `parkervcp` | +| [Charles Morgan](https://github.com/notAreYouScared) | `areyouscared` | +| [Alex 'Scai' Vlad](https://github.com/alexevladgabriel)| `.scai` | +| [Boy132](https://github.com/boy132) | `boy132` | +| [Martin Oscar](https://github.com/RMartinOscar) | `rmartinoscar` | + +### Community Staff - - If you notice anything that raises a concern, please reach out directly to **team@pelican.dev** - For security reasons, we ask that you handle security disclosures responsibly and **avoid posting them on GitHub.** - +| Name | Discord | +|------------------------------------------------|---------------| +| [Trixter](https://github.com/TrixterTheTux) | `trixter` | +| [Quinten](https://github.com/QuintenQVD0) | `quintenqvd` | +| [Red-Thirten](https://github.com/redthirten) | `red_thirten` | diff --git a/docs/panel/advanced/artisan.mdx b/docs/panel/advanced/artisan.mdx deleted file mode 100644 index 10fed0c6..00000000 --- a/docs/panel/advanced/artisan.mdx +++ /dev/null @@ -1,267 +0,0 @@ -# Artisan Commands -This is very much a WIP! Many Many commands, Layout might change. - -Updated: 01/11/2025 -## User Commands -### Create a User - -Creates a user on the system via the CLI. -```sh -php artisan p:user:make [options] -``` - -```sh -Options: - --email[=EMAIL] - --username[=USERNAME] - --password[=PASSWORD] - --admin[=ADMIN] - --no-password - -q, --quiet Do not output any message - -V, --version Display this application version - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` - -### Delete a User - -Deletes a user from the Panel if no servers are attached to their account. -```sh -php artisan p:user:delete [options] -``` - -```sh -Options: - --user[=USER] - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` - -### Disable 2fa for a single User - -Disable two-factor authentication for a specific user in the Panel. -```sh -php artisan p:user:disable2fa [options] -``` - -```sh -Options: - --email[=EMAIL] The email of the user to disable 2-Factor for. - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question - -``` - -## Editing the Environment - -### Editing Cache -```sh -php artisan p:environment:cache [options] -``` - -```sh -Options: - --driver[=DRIVER] The cache driver backend to use. - --redis-host[=REDIS-HOST] Redis host to use for connections. - --redis-user[=REDIS-USER] User used to connect to redis. - --redis-pass[=REDIS-PASS] Password used to connect to redis. - --redis-port[=REDIS-PORT] Port to connect to redis over. - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` - -### Editing Database -```sh -php artisan p:environment:database [options] -``` - -```sh -Options: - --driver[=DRIVER] The database driver backend to use. - --database[=DATABASE] The database to use. - --host[=HOST] The connection address for the MySQL/ MariaDB server. - --port[=PORT] The connection port for the MySQL/ MariaDB server. - --username[=USERNAME] Username to use when connecting to the MySQL/ MariaDB server. - --password[=PASSWORD] Password to use for the MySQL/ MariaDB database. - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -### Editing Mail -```sh -php artisan p:environment:mail [options] -``` - -```sh -Options: - --driver[=DRIVER] The mail driver to use. - --email[=EMAIL] Email address that messages from the Panel will originate from. - --from[=FROM] The name emails from the Panel will appear to be from. - --encryption[=ENCRYPTION] - --host[=HOST] - --port[=PORT] - --endpoint[=ENDPOINT] - --username[=USERNAME] - --password[=PASSWORD] - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -### Editing Queue -```sh -php artisan p:environment:queue [options] -``` - -```sh -Options: - --driver[=DRIVER] The queue driver backend to use. - --redis-host[=REDIS-HOST] Redis host to use for connections. - --redis-user[=REDIS-USER] User used to connect to redis. - --redis-pass[=REDIS-PASS] Password used to connect to redis. - --redis-port[=REDIS-PORT] Port to connect to redis over. - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -### Editing Queue Service -```sh -php artisan p:environment:queue-service [options] -``` - -```sh -Options: - --service-name[=SERVICE-NAME] Name of the queue worker service. - --user[=USER] The user that PHP runs under. - --group[=GROUP] The group that PHP runs under. - --overwrite Force overwrite if the service file already exists. - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -### Editing Session -```sh -php artisan p:environment:session [options] -``` - -```sh -Options: - --driver[=DRIVER] The queue driver backend to use. - --redis-host[=REDIS-HOST] Redis host to use for connections. - --redis-user[=REDIS-USER] User used to connect to redis. - --redis-pass[=REDIS-PASS] Password used to connect to redis. - --redis-port[=REDIS-PORT] Port to connect to redis over. - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -### Setting cache, queue & session driver at once -```sh -php artisan p:redis:setup [options] -``` - -```sh -Options: - --redis-host[=REDIS-HOST] Redis host to use for connections. - --redis-user[=REDIS-USER] User used to connect to redis. - --redis-pass[=REDIS-PASS] Password used to connect to redis. - --redis-port[=REDIS-PORT] Port to connect to redis over. - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -### Editing Setup -```sh -php artisan p:environment:setup [options] -``` - -```sh -Options: - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` - -## Migrations -### Migration Command -```sh -php artisan migrate [options] -``` - -```sh -Options: - --database[=DATABASE] The database connection to use - --force Force the operation to run when in production - --path[=PATH] The path(s) to the migrations files to be executed (multiple values allowed) - --realpath Indicate any provided migration file paths are pre-resolved absolute paths - --schema-path[=SCHEMA-PATH] The path to a schema dump file - --pretend Dump the SQL queries that would be run - --seed Indicates if the seed task should be re-run - --seeder[=SEEDER] The class name of the root seeder - --step Force the migrations to be run so they can be rolled back individually - --graceful Return a successful exit code even if an error occurs - --isolated[=ISOLATED] Do not run the command if another instance of the command is already running [default: false] - -q, --quiet Do not output any message - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -### Running Migations -```sh -php artisan migrate -``` - -### Rollback previous Migration -```sh -php artisan migrate:rollback [options] -``` - -```sh -Options: - --database[=DATABASE] The database connection to use - --force Force the operation to run when in production - --path[=PATH] The path(s) to the migrations files to be executed (multiple values allowed) - --realpath Indicate any provided migration file paths are pre-resolved absolute paths - --pretend Dump the SQL queries that would be run - --step[=STEP] The number of migrations to be reverted - --batch=BATCH The batch of migrations (identified by their batch number) to be reverted - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` - -### Check Migration Status -```sh -php artisan migrate:status [options] -``` -```sh -Options: - --database[=DATABASE] The database connection to use - --pending[=PENDING] Only list pending migrations [default: false] - --path[=PATH] The path(s) to the migrations files to use (multiple values allowed) - --realpath Indicate any provided migration file paths are pre-resolved absolute paths - --ansi|--no-ansi Force (or disable --no-ansi) ANSI output - -n, --no-interaction Do not ask any interactive question -``` -Providing no extra options, `php artisan migrate:status`, You should see an output similar to the below -```sh title='Migration Status Output' - Migration name .............................................................................. Batch / Status - 2016_01_23_195641_add_allocations_table ............................................................ [1] Ran - 2016_01_23_195851_add_api_keys ..................................................................... [1] Ran - ... - ... - 2024_07_12_095213_fix_missing_sqlite_foreign_keys .................................................. [1] Ran - 2024_08_13_171337_fix_allocation_server_foreign_key ................................................ [2] Ran -``` -If any show `PENDING` or `FAILED`. Open a support thread on our discord for further assistance. - -## Clearing Cache - -The below commands are helpful if you need to clear the config or application cache. - -```sh -php artisan cache:clear # Clears application cache -``` -```sh -php artisan config:clear # Clears configuration cache -``` diff --git a/docs/panel/advanced/mysql.mdx b/docs/panel/advanced/mysql.mdx index b08f7b8e..2eb08510 100644 --- a/docs/panel/advanced/mysql.mdx +++ b/docs/panel/advanced/mysql.mdx @@ -1,60 +1,67 @@ -# MySQL - -## Install MariaDB - -MariaDB is a MySQL fork and the preferred MySQL software. Run the following commands to quickly install it. - -```sh -curl -sSL https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash -sudo apt install -y mariadb-server -``` - -## Create User & Database - -### Logging In - -After installing you want to login to the MySQL command line where we will be executing statements to get -things setup. To do so, simply run the command below and provide the Root MySQL account's password that you setup when -installing MySQL. If you do not remember doing this, chances are you can just hit enter as no password is set. - -```sh -mysql -u root -p -``` - -### Creating User - -Next, we will create a user called `pelican` and allow logins from localhost which prevents any external connections -to our database. You can also use `%` as a wildcard or enter a numeric IP. We will also set the account password -to `somePassword`. - -```sql -CREATE USER 'pelican'@'127.0.0.1' IDENTIFIED BY 'somePassword'; -``` - -### Creating Database - -Next, we need to create a database for the panel. In this tutorial we will be naming the database `panel`, but you can -substitute that for whatever name you wish. - -```sql -CREATE DATABASE panel; -``` - -### Assigning Permissions - -Finally, we need to tell MySQL that our pelican user should have access to the panel database. To do this, simply -run the command below. - -```sql -GRANT ALL PRIVILEGES ON panel.* TO 'pelican'@'127.0.0.1'; -``` - -## Setup Pelican for MySQL - -If you are switching to MySQL after installing the Panel you have to run the database setup command below. -**You do not have to run this if this is the first time you are installing the Panel. You will provide the database data via the Web Installer.** - -```sh -cd /var/www/pelican -php artisan p:environment:database -``` +--- +pagination_prev: null +pagination_next: null +--- + +# MySQL + +A brief guide on how to install and setup MariaDB. + +## Install MariaDB + +MariaDB is a MySQL fork and the preferred MySQL software. Run the following commands to quickly install it. + +```sh +curl -sSL https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash +sudo apt install -y mariadb-server +``` + +## Create User & Database + +### Logging In + +After installing you want to login to the MySQL command line where we will be executing statements to get +things setup. To do so, simply run the command below and provide the Root MySQL account's password that you setup when +installing MySQL. If you do not remember doing this, chances are you can just hit enter as no password is set. + +```sh +mysql -u root -p +``` + +### Creating User + +Next, we will create a user called `pelican` and allow logins from localhost which prevents any external connections +to our database. You can also use `%` as a wildcard or enter a numeric IP. We will also set the account password +to `somePassword`. + +```sql +CREATE USER 'pelican'@'127.0.0.1' IDENTIFIED BY 'somePassword'; +``` + +### Creating Database + +Next, we need to create a database for the panel. In this tutorial we will be naming the database `panel`, but you can +substitute that for whatever name you wish. + +```sql +CREATE DATABASE panel; +``` + +### Assigning Permissions + +Finally, we need to tell MySQL that our pelican user should have access to the panel database. To do this, simply +run the command below. + +```sql +GRANT ALL PRIVILEGES ON panel.* TO 'pelican'@'127.0.0.1'; +``` + +## Setup Pelican for MySQL + +If you are switching to MySQL after installing the Panel you have to run the database setup command below. +**You do not have to run this if this is the first time you are installing the Panel. You will provide the database data via the Web Installer.** + +```sh +cd /var/www/pelican +php artisan p:environment:database +``` diff --git a/docs/panel/advanced/redis.mdx b/docs/panel/advanced/redis.mdx index f794a717..3b9209a7 100644 --- a/docs/panel/advanced/redis.mdx +++ b/docs/panel/advanced/redis.mdx @@ -1,5 +1,12 @@ +--- +pagination_prev: null +pagination_next: null +--- + # Redis +A brief guide on how to install and setup Redis. + ## Install Redis To install Redis you first need add their repository. @@ -25,8 +32,6 @@ sudo systemctl enable --now redis-server ## Setup Pelican for Redis -### Use Redis as driver - If you are switching to Redis after installing the Panel you have to run the setup command below. **You do not have to run this if this is the first time you are installing the Panel. You will provide the redis data via the Web Installer.** diff --git a/docs/panel/getting-started.mdx b/docs/panel/getting-started.mdx deleted file mode 100644 index b2c148d8..00000000 --- a/docs/panel/getting-started.mdx +++ /dev/null @@ -1,92 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Getting Started - -Pelican Panel is designed to run on your webserver. - -You are expected to read through our documentation. -We have spent a lot of time curating these docs for the community, -so please take some time to read through them before asking for help on the forums! - - - **You should have some basic familiarity with Linux before you proceed!** - - - - Pelican is currently in **Beta**! Some things might change / break between beta versions! - - -### Picking an Operating System (OS) - -Pelican runs on a wide range of operating systems, so pick whichever you are most comfortable using. Note: Other OS's, not listed below, might still work. - - - OpenVZ, **unless specifically configured**, will **not** work with Pelican. - - -| Operating System | Version | Supported | Notes | -|:----------------:|:--------:|:---------:|:---------------------------------------------------------------------:| -| **Ubuntu** | 22.04 | ✅︎︎ | | -| | **24.04**| ✅︎ | Documentation written assuming Ubuntu 24.04 as the base OS. | -| **Alma Linux** | 10 | ✅︎ | | -| | 9 | ⚠️ | **No SQLite Support** | -| | 8 | ⚠️ | **No SQLite Support** | -| **Rocky Linux** | 10 | ✅︎ | | -| | 9 | ⚠️ | **No SQLite Support** | -| | 8 | ⚠️ | **No SQLite Support** | -| **CentOS** | 10 | ✅︎ | | -| **Debian** | 11 | ⚠️ | **No SQLite Support** | -| | 12 | ✅︎ | | - -SQLite support depends on [libsqlite3-0_3.35+](https://pkgs.org/download/libsqlite3-0) being on the host system. -**No SQLite Support** means you'll have to build the package from source. - -### Dependencies - -For the Panel you need to install **PHP `8.5` (recommended), `8.4`, `8.3` or `8.2`**, with the following **extensions**: -`gd`, `mysql`, `mbstring`, `bcmath`, `xml`, `curl`, `zip`, `intl`, `sqlite3` and `fpm`. - -You will also need a Webserver. Currently, **Apache, NGINX or Caddy** are supported. - -If you want to use MySQL, MariaDB or PostgreSQL for the panel database make sure to install either **MySQL 8+, MariaDB 10.6+ or PostgreSQL 14+**. (both client and server!) - -Finally, for some commands during the installation you need `curl`, `tar` and `unzip`. - - - Please make sure you installed **all** needed dependencies before continuing! - - -### Create Directories & Downloading Files - -The first step in this process is to create the folder where the panel will live and then move ourselves into that -newly created folder. - -```sh -sudo mkdir -p /var/www/pelican -cd /var/www/pelican -``` - -Once you have created a new directory to use and moved into it, you'll need to download the Panel files. -This is as simple as using `curl` to download the latest release. - -```sh -curl -L https://github.com/pelican-dev/panel/releases/latest/download/panel.tar.gz | sudo tar -xzv -``` - -### Install Composer - -Next we will set up Composer along with the required dependencies. - -``` bash -curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer -``` - -```sh -sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader -``` - - - Even though composer might tell you that you have outdated dependencies, do **not** run `composer update`! - diff --git a/docs/panel/advanced/docker.mdx b/docs/panel/install/dockerized.mdx similarity index 56% rename from docs/panel/advanced/docker.mdx rename to docs/panel/install/dockerized.mdx index d866f174..289cab4f 100644 --- a/docs/panel/advanced/docker.mdx +++ b/docs/panel/install/dockerized.mdx @@ -1,10 +1,39 @@ -# Docker +--- +pagination_prev: null +pagination_next: null +--- -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) +# Dockerized installation -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). +Run the Pelican Panel inside a docker container. -## Basics +:::danger + **You should have some basic familiarity with Docker before you proceed!** +::: + +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. + +## Install Docker + +For a quick install of Docker CE, you can use the command below: + +```sh +curl -sSL https://get.docker.com/ | CHANNEL=stable sudo sh +``` + +:::info[Trouble installing?] + 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. +::: + +### Start Docker on Boot + +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. + +```sh +sudo systemctl enable --now docker +``` + +## Setup compose file The easiest deployment method is using the standard `compose.yml` file. @@ -12,25 +41,48 @@ This configuration includes an integrated web server that will automatically obt ### Create compose.yml -```yml {17,18} title="compose.yml" +```yml {4-7,9-10,12} title="compose.yml" +x-common: + panel: + &panel-environment + APP_URL: "http://localhost" + LE_EMAIL: "USEYOUROWNEMAILHERE@example.com" # email to be used for let's encrypt certificates + APP_DEBUG: "false" + APP_ENV: "production" + + # BEHIND_PROXY: true # uncomment to run behind a proxy + # TRUSTED_PROXIES: 127.0.0.1,172.17.0.1,172.20.0.1 # defaults are for local proxies + + # SKIP_CADDY: true # enable when not using caddy. + +# +# ------------------------------------------------------------------------------------------ +# DANGER ZONE BELOW +# +# The remainder of this file likely does not need to be changed. Please only make modifications +# below if you understand what you are doing. +# + services: panel: image: ghcr.io/pelican-dev/panel:latest - restart: always + build: . + restart: unless-stopped networks: - default ports: - "80:80" - "443:443" + # - "81:80" # if you are behind a proxy uncomment this line and comment out 80 and 443 + # - "9000:9000" # enable when not using caddy to be able to reach php-fpm extra_hosts: - - "host.docker.internal:host-gateway" + - "host.docker.internal:host-gateway" # shows the panel on the internal docker network as well. usually '172.17.0.1' volumes: - pelican-data:/pelican-data - pelican-logs:/var/www/html/storage/logs environment: + <<: [*panel-environment] XDG_DATA_HOME: /pelican-data - APP_URL: "http://localhost" - ADMIN_EMAIL: "USEYOUROWNEMAILHERE@example.com" volumes: pelican-data: @@ -46,12 +98,12 @@ networks: ### Set Required Environment Variables 1. Set `APP_URL` to the base URL your panel will be reachable on, including the protocol (https:// or http://) and port. - - 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). -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. + - Note that Caddy, the integrated web server, 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). +2. Set the `LE_EMAIL` to your email address. Caddy will use this email address to generate a LetsEncrypt SSL certificate if you are serving via HTTPS. Now, close and save changes to `compose.yml`. -### Starting +## Start the container From the directory in which the compose file is located, run: @@ -67,14 +119,15 @@ The first time the container starts, it will generate an `APP_KEY` which is used docker compose logs panel | grep 'Generated app key:' ``` -### Installing +## Finish setup Open the installer in your browser at `APP_URL/installer` to finish setting up the panel. :::note -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. + 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. ::: + #### Sensible Driver Defaults: * Cache Driver: Filesystem @@ -84,7 +137,7 @@ The first time the container starts after installing or updating, it will apply For other configuration, such as UI options, CAPTCHA, email, backups and OAuth, head to the settings menu in the admin panel. -### Stopping +## Stopping 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: @@ -92,7 +145,7 @@ The panel will automatically restart if the container crashes or the host restar docker compose down ``` -### Uninstalling +## Uninstalling To uninstall the panel, navigate to the directory containing `compose.yml` and run: @@ -101,14 +154,14 @@ docker compose down -v ``` :::danger - **This will permanently delete the panel and all associated data including the SQLite database and your encryption key.** + **This will permanently delete the panel and all associated data including the SQLite database and your encryption key.** ::: ## Advanced Options ### Custom Caddyfile -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. +The default Caddyfile will work for standard installations. If you need to edit the configuration of the integrated web server, 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. This example assumes there is a Caddyfile in the same directory as the `compose.yml` file. @@ -131,7 +184,7 @@ services: environment: XDG_DATA_HOME: /pelican-data APP_URL: "http://localhost" - ADMIN_EMAIL: "USEYOUROWNEMAILHERE@example.com" + LE_EMAIL: "USEYOUROWNEMAILHERE@example.com" volumes: pelican-data: @@ -164,7 +217,7 @@ An example Caddyfile for hosting the panel behind a reverse proxy is shown below ``` :::info - **Note:** If the trusted directive is not set or improperly configured, file uploads will fail. Commonly, when the reverse proxy is running outside of Docker, the IP address will not match `127.0.0.1`, but will instead match a Docker bridge interface or `docker0`. + **Note:** If the trusted directive is not set or improperly configured, file uploads will fail. Commonly, when the reverse proxy is running outside of Docker, the IP address will not match `127.0.0.1`, but will instead match a Docker bridge interface or `docker0`. ::: #### Raising file upload limits @@ -183,4 +236,4 @@ The default file upload limit is 2MB. To raise this limit, modify the `Caddyfile } file_server } -``` +``` \ No newline at end of file diff --git a/docs/panel/webserver-config.mdx b/docs/panel/install/standalone.mdx similarity index 73% rename from docs/panel/webserver-config.mdx rename to docs/panel/install/standalone.mdx index c1919430..9e85ce26 100644 --- a/docs/panel/webserver-config.mdx +++ b/docs/panel/install/standalone.mdx @@ -1,21 +1,93 @@ -import Admonition from '@theme/Admonition'; +--- +pagination_prev: null +pagination_next: null +--- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Webserver Configuration +# Standalone installation + +Run the Pelican Panel directly on a web server. + +:::danger + **You should have some basic familiarity with Linux before you proceed!** +::: + +## Requirements + +### Operating System (OS) + +The Panel runs on a wide range of operating systems, so pick whichever you are most comfortable using. +This documentation assumes a Debian-based OS with `apt`. + +:::info +SQLite support depends on [libsqlite3-0_3.35+](https://pkgs.org/download/libsqlite3-0) being on the host system. +OS's that do _not_ support SQLite include: Debian 11, Alma Linux 8 or 9, Rocky Linux 8 or 9. +::: + +### Dependencies + +For the Panel you need to install **PHP `8.5` (recommended), `8.4`, `8.3` or `8.2`**, with the following **extensions**: +`gd`, `mysql`, `mbstring`, `bcmath`, `xml`, `curl`, `zip`, `intl`, `sqlite3` and `fpm`. + +You will also need a web server. Currently, **Apache, NGINX or Caddy** are supported. + +If you want to use MySQL, MariaDB or PostgreSQL for the panel database make sure to install either **MySQL 8+, MariaDB 10.6+ or PostgreSQL 14+**. (both client and server!) + +Finally, for some commands during the installation you need `curl`, `tar` and `unzip`. + +:::warning + Please make sure you installed **all** needed dependencies before continuing! +::: - - When using the SSL (https) configuration you MUST create SSL certificates, otherwise your webserver will fail to start. - See the [Creating SSL Certificates](../guides/ssl) documentation page to learn how to create these certificates before continuing. - +## Download Panel files + +The first step in this process is to create the folder where the panel will live and then move ourselves into that +newly created folder. + +```sh +sudo mkdir -p /var/www/pelican +cd /var/www/pelican +``` + +Once you have created a new directory to use and moved into it, you'll need to download the Panel files. +This is as simple as using `curl` to download the latest release. + +```sh +curl -L https://github.com/pelican-dev/panel/releases/latest/download/panel.tar.gz | sudo tar -xzv +``` + +## Install Composer + +Next we will set up Composer along with the required dependencies. + +```sh +curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer +``` + +```sh +sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader +``` + +:::info + Even though composer might tell you that you have outdated dependencies, do **not** run `composer update`! +::: + +## Web server Configuration + +:::info + When using the SSL (https) configuration you MUST create SSL certificates, otherwise your web server will fail to start. + See the [Creating SSL Certificates](../../guides/ssl) documentation page to learn how to create these certificates before continuing. +::: - + :::warning[php & fpm] If you're **not** using php8.5, you will need to edit the config file to point to the proper php fpm socket. The line is highlighted below. - + ::: First, remove the default NGINX configuration. ```sh sudo rm /etc/nginx/sites-enabled/default @@ -24,9 +96,9 @@ import TabItem from '@theme/TabItem'; `pelican.conf` and place the file in `/etc/nginx/sites-available/`. - + :::warning **Note:** IPs cannot be used with SSL. - + ::: ```nginx {5,11,25-26,47} title="/etc/nginx/sites-available/pelican.conf" server_tokens off; @@ -146,7 +218,8 @@ import TabItem from '@theme/TabItem'; ``` - ### Enabling Configuration + + #### Enabling Configuration The final step is to enable your NGINX configuration and restart it. @@ -171,12 +244,12 @@ import TabItem from '@theme/TabItem'; Now, you should paste the contents of the file below, replacing `` with your domain name being used in a file called `pelican.conf` and place the file in `/etc/apache2/sites-available/`. - Note: When using Apache, make sure you have the `libapache2-mod-php` package installed or else PHP will not display on your webserver. + Note: When using Apache, make sure you have the `libapache2-mod-php` package installed or else PHP will not display on your web server. - + :::warning **Note:** IPs cannot be used with SSL. - + ::: ```apacheconf {2,10,24-25} title="/etc/apache2/sites-available/pelican.conf" ServerName @@ -225,15 +298,16 @@ import TabItem from '@theme/TabItem'; ``` - ### Enabling Configuration + + #### Enabling Configuration Once you've created the file above, simply run the commands below. - + :::warning[php & fpm] If you're **not** using php8.5, you will need to edit the command to point to enable the correct mod. The line is highlighted below. - + ::: ```sh {3} sudo a2ensite pelican.conf @@ -249,11 +323,11 @@ import TabItem from '@theme/TabItem'; - + :::warning[php & fpm] If you're **not** using php8.5, you will need to edit the config file to point to the proper php fpm socket. The line is highlighted below. - + ::: First, remove the default Caddy configuration. ```sh @@ -264,9 +338,9 @@ import TabItem from '@theme/TabItem'; - + :::warning **Note:** IPs cannot be used with SSL. - + ::: ```caddy {9,14} title="/etc/caddy/Caddyfile" { servers :443 { @@ -372,7 +446,9 @@ import TabItem from '@theme/TabItem'; ``` - ### Enabling Configuration + + #### Enabling Configuration + The final step is to restart Caddy. ```sh @@ -380,3 +456,57 @@ import TabItem from '@theme/TabItem'; ``` + +## Panel Setup + +The core environment is easily configured using a single CLI command & the web installer built into the app. +These steps will cover setting up things such as sessions, caching, database credentials, and email sending. + +Running `php artisan p:environment:setup` will, if it does not exist, auto-create the required `.env` file and generate a `APP_KEY`. + +```sh +sudo php artisan p:environment:setup +``` + +:::warning[BACK UP `APP_KEY`!] + **Back up** your encryption key (APP_KEY in the `.env` file). This is used as an encryption key for all data that needs to be stored securely (e.g. api keys). + Store it somewhere safe - not just on your server. If you lose it all encrypted data is irrecoverable -- **even if you have database backups.** +::: + +## Setting Permissions + +The next step in the installation process is to set the correct permissions on the Panel files so that the web server can use them correctly. + +```sh +sudo chmod -R 755 storage/* bootstrap/cache/ +``` + + + + ```sh + sudo chown -R www-data:www-data /var/www/pelican + ``` + + + ```sh + sudo chown -R nginx:nginx /var/www/pelican + ``` + + + ```sh + sudo chown -R apache:apache /var/www/pelican + ``` + + + +## Web Installer + +Once you've set the proper permissions, finish the Panel install via the web installer. +The web installer is located at `/installer` or `/installer`, e.g. `https://panel.example.com/installer` + +During this step you will choose the default drivers, create the queue worker and create the default admin user. + +:::info[Want something advanced?] + Make sure to read the [MySQL guide](../advanced/mysql) first if you want to use MySQL/MariaDB instead of SQLite! + If you want to use Redis make sure to read the [Redis guide](../advanced/redis) first. +::: \ No newline at end of file diff --git a/docs/panel/optional-config.mdx b/docs/panel/optional-config.mdx index 2a2f7b62..c0d400e5 100644 --- a/docs/panel/optional-config.mdx +++ b/docs/panel/optional-config.mdx @@ -1,4 +1,4 @@ -# Optional Configuration +# Additional Configuration ## Backups @@ -12,7 +12,6 @@ Make sure to clear the config cache (`cd /var/www/pelican && php artisan config: By default, Pelican uses local storage via Wings for backups. That said, this method of backup storage can be explicitly set within the Settings Page on the Admin side of the panel. - Please note that, when using local storage via Wings, the destination for backups is set in the Wings config file with the following setting key: ```yml {2} @@ -104,4 +103,4 @@ Run the following command in your `/var/www/pelican` directory. ```sh php artisan p:user:disable2fa -``` +``` \ No newline at end of file diff --git a/docs/panel/panel-setup.mdx b/docs/panel/panel-setup.mdx deleted file mode 100644 index f780d22c..00000000 --- a/docs/panel/panel-setup.mdx +++ /dev/null @@ -1,56 +0,0 @@ -import Admonition from '@theme/Admonition'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Panel Setup - -The core environment is easily configured using a single CLI command & the web installer built into the app. -These steps will cover setting up things such as sessions, caching, database credentials, and email sending. - -Running `php artisan p:environment:setup` will, if it does not exist, auto create the required `.env` file and generate a `APP_KEY`. - -```sh -sudo php artisan p:environment:setup -``` - - - **Back up** your encryption key (APP_KEY in the `.env` file). This is used as an encryption key for all data that needs to be stored securely (e.g. api keys). - Store it somewhere safe - not just on your server. If you lose it all encrypted data is irrecoverable -- **even if you have database backups.** - - -### Setting Permissions - -The next step in the installation process is to set the correct permissions on the Panel files so that the webserver can -use them correctly. - -```sh -sudo chmod -R 755 storage/* bootstrap/cache/ -``` - - - - ```sh - sudo chown -R www-data:www-data /var/www/pelican - ``` - - - ```sh - sudo chown -R nginx:nginx /var/www/pelican - ``` - - - ```sh - sudo chown -R apache:apache /var/www/pelican - ``` - - - -### Web-Installer - -Once you've set the proper permissions, continue the Panel install on the web interface. -The web installer is located at `/installer` or `/installer`. - - - Make sure to read the [MySQL guide](./advanced/mysql) first if you want to use MySQL/ MariaDB instead of SQLite! - If you want to use Redis make sure to read the [Redis guide](./advanced/redis) first. - diff --git a/docs/panel/advanced/plugins.mdx b/docs/panel/plugins.mdx similarity index 96% rename from docs/panel/advanced/plugins.mdx rename to docs/panel/plugins.mdx index 57ec5253..1c9ca4b9 100644 --- a/docs/panel/advanced/plugins.mdx +++ b/docs/panel/plugins.mdx @@ -1,4 +1,8 @@ -import Admonition from '@theme/Admonition'; +--- +pagination_prev: null +pagination_next: null +--- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -6,9 +10,9 @@ import TabItem from '@theme/TabItem'; Plugins allow you to add new functionality to the panel without modifying any panel core files. - +:::warning The plugin system is still in development and features might be missing! - +::: ## Install a Plugin @@ -21,22 +25,22 @@ Plugins allow you to add new functionality to the panel without modifying any pa - +:::info[Need some plugins?] Check out our [Plugins repo](https://github.com/pelican-dev/plugins)! It contains free and open source plugins created by the Pelican team and the community. We are also working on adding a plugin marketplace to the [Hub](https://hub.pelican.dev). - +::: ## Create a Plugin - +:::danger You **need** at least basic [PHP](https://php.net), [Laravel](https://laravel.com) and [Filament](https://filamentphp.com) knowledge to create plugins! - +::: Run `php artisan p:plugin:make` inside your panel directory (`/var/www/pelican` by default) to create the basic files and folders for your new plugin. This will create the `plugin.json`, the main plugin file, a config file and a service provider. - +:::info[Need help?] Visit our [Discord](https://discord.gg/pelican-panel) if you need any help when creating plugins! - +::: ### Plugin Structure @@ -48,9 +52,9 @@ Everything is auto-discovered and service providers, artisan commands, migration The only exception to a normal Laravel project is the `app` folder, it is called `src` instead. Besides that, is still follows the same sub-structure, e.g. models go in `src/Models` and service providers are in `src/Providers`. - +:::info The plugin id and the plugin root folder name need to match! - +::: #### plugin.json @@ -71,9 +75,9 @@ Most of the fields inside the `plugin.json` are generated when running the [arti | panel_version | No | The panel version required for the plugin. See [below](#panel-version) for more information. | | composer_packages | No | Array of additional composer packages. Key is the package name and value is the version. See [below](#additional-composer-dependencies) for more information. | - +:::info You can ignore the `meta` fields. Those are used internally to keep track of the plugin status and load order. - +::: #### Update URL @@ -271,9 +275,9 @@ public function saveSettings(array $data): void } ``` - +:::info[Naming Conventions] When adding new environment variables make sure to prefix them with your plugin id, e.g. `MYPLUGIN_TEST_INPUT` and not just `TEST_INPUT`. - +::: ### Modify existing resources @@ -350,10 +354,10 @@ public function register(): void ## Publish a Plugin - +:::danger While Pelican is still in beta, please do **not** sell plugins. Also, if possible, please make them open source. During the beta we still add new features and change existing ones. So keeping your plugins open helps us to improve the plugin system! - +::: To publish a plugin you only need to do two things: @@ -362,12 +366,12 @@ To publish a plugin you only need to do two things: And that's it! Now you can take the zip file and share it with the world! - +:::info[Marketplace] We are currently working on adding a plugin marketplace to the [Hub](https://hub.pelican.dev). Until then you can publish your plugins on our [plugins repo](https://github.com/pelican-dev/plugins). You can also share them in the `#plugins` channel in our [Discord](https://discord.gg/pelican-panel). - +::: - +:::info[License] You can license your plugin code under whatever license you want. You do not have to use the same license as the panel! You also don't have to open source your plugin code. But if you do want to open source it we recommend [MIT](https://choosealicense.com/licenses/mit) or [GPL v3](https://choosealicense.com/licenses/gpl-3.0) as license. - +::: diff --git a/docs/panel/update.mdx b/docs/panel/update.mdx index 06cfc2b9..49b0dd52 100644 --- a/docs/panel/update.mdx +++ b/docs/panel/update.mdx @@ -1,10 +1,14 @@ -import Admonition from '@theme/Admonition'; +--- +pagination_prev: null +pagination_next: null +--- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Updating the Panel +# Update -This documentation covers the process for updating the panel portion of Pelican. +A brief guide on how to update the Pelican Panel to the latest version. ## Version Requirements @@ -29,7 +33,7 @@ You have two options for updating: use the automatic update script (recommended) ``` - ### Enter Maintenance Mode + #### Enter Maintenance Mode Whenever you are performing an update you should be sure to place your Panel into maintenance mode. This will prevent users from encountering unexpected errors. @@ -39,7 +43,7 @@ You have two options for updating: use the automatic update script (recommended) sudo php artisan down ``` - ### Download Update + #### Download Update The first step in the update process is to download the new panel files from GitHub. The command below will download the release archive for the most recent version of Pelican, save it in the current directory and will automatically @@ -50,36 +54,36 @@ You have two options for updating: use the automatic update script (recommended) ``` Once the archive is downloaded and extracted we need to set the correct permissions on the cache and storage directories to avoid - any webserver related errors. + any web server related errors. ```sh sudo chmod -R 755 storage/* bootstrap/cache ``` - ### Update Dependencies + #### Update Dependencies ```sh sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader ``` - + :::info Even though composer might tell you that you have outdated dependencies, do **not** run `composer update`! - + ::: - ### Create storage symlinks + #### Create storage symlinks ```sh sudo php artisan storage:link ``` - ### Cache components + #### Cache components ```sh sudo php artisan optimize:clear sudo php artisan filament:optimize ``` - ### Update Database + #### Update Database You'll also need to update your database schema. Running the command below will update the schema and ensure the default eggs we ship are up to date (and add any new ones we might have). Just @@ -89,7 +93,7 @@ You have two options for updating: use the automatic update script (recommended) sudo php artisan migrate --seed --force ``` - ### Themes + #### Themes If you previously had any themes installed you need to manually build the panel assets again: @@ -98,13 +102,13 @@ You have two options for updating: use the automatic update script (recommended) yarn build ``` - ### Set Permissions + #### Set Permissions The last step is to set proper ownership of the files. In most cases this is `www-data` but can vary from system to system — sometimes being `nginx`, `caddy`, `apache`, or even `nobody`. - + ```sh sudo chown -R www-data:www-data /var/www/pelican ``` @@ -121,7 +125,7 @@ You have two options for updating: use the automatic update script (recommended) - ### Restart Queue Workers + #### Restart Queue Workers After _every update_ you should restart the queue worker. @@ -129,7 +133,7 @@ You have two options for updating: use the automatic update script (recommended) sudo php artisan queue:restart ``` - ### Exit Maintenance Mode + #### Exit Maintenance Mode Now that everything has been updated you need to exit maintenance mode. @@ -138,4 +142,3 @@ You have two options for updating: use the automatic update script (recommended) ``` - diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx index be1bf9b2..4ed91d6f 100644 --- a/docs/troubleshooting.mdx +++ b/docs/troubleshooting.mdx @@ -1,8 +1,8 @@ --- -id: troubleshooting +pagination_prev: null +pagination_next: null --- -import Admonition from '@theme/Admonition'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -19,13 +19,13 @@ tail -n 1000 /var/www/pelican/storage/logs/laravel-$(date +%F).log | grep "\[$(d
Common errors - * `ErrorException: file_put_contents(_____): failed to open stream: Permission denied`: Wrong file permissions/ ownership for the panel files, see [below](#wrong-file-permissions). - * `502 Bad Gateway Error`: Make sure that php-fpm is running and that you are using the correct php version in your webserver config. + * `ErrorException: file_put_contents(_____): failed to open stream: Permission denied`: Wrong file permissions/ownership for the panel files, see [below](#wrong-file-permissions). + * `502 Bad Gateway Error`: Make sure that php-fpm is running and that you are using the correct php version in your web server config. * `CSRF token mismatch`: Enable SSL for your Panel with HTTPS protocol scheme in the `APP_URL`, or set `SESSION_SECURE_COOKIE` to `false` in your `.env` file. * `Connection refused [tcp://_______:6379]`: Redis isn't running or isn't reachable for some other reason. (start by checking the status of the redis service: `systemctl status redis-server`) * `SSL: no alternative certificate subject name matches target host name '_______'`: The used SSL certificate for your panel isn't valid for your panel domain, see [this guide](./guides/ssl) for creating a new SSL certificate. * `General error: 8 attempt to write a readonly database`: Your `database.sqlite` has wrong file permissions and is read-only. Make sure the file is writable and owned by the correct user. - * `Class '_____' not found`: This usually means you are missing php extensions. Make sure [all needed extensions](./panel/getting-started#dependencies) are installed and that you are using the correct php version. + * `Class '_____' not found`: This usually means you are missing php extensions. Make sure [all needed extensions](./panel/install/standalone#dependencies) are installed and that you are using the correct php version. * `Connection timed out after 5001 milliseconds for _______:8080`: Your panel can't reach wings, see the wings connection issues steps below.
@@ -62,22 +62,22 @@ It should say that the service is active and running. If its in a failed state r
Common errors - * `open /etc/letsencrypt/live/_____________/fullchain.pem: no such file or directory`: The SSL certificate for wings is missing, see [this guide](./guides/ssl) for creating a SSL certificate. + * `open /etc/letsencrypt/live/_____________/fullchain.pem: no such file or directory`: The SSL certificate for wings is missing, see [this guide](./guides/ssl) for creating an SSL certificate. * `Pool overlaps with other one on this address space`: You already have a docker network using the default subnet. (`172.18.0.0/16`) Change the subnet in your wings config file and use `systemctl stop wings && docker network rm pelican_nw && systemctl start wings` to apply the change. - * `Error response from Panel: AccessDeniedHttpException: You are not authorized to access this resource. (HTTP/403)`: Your wings token is wrong, you need [update the token in your config.yml file](./wings/install#configure) - * `Error response from Panel: _MissingResponseCode: No error response returned from API endpoint`: Your panel is not responding correctly. This usually happens when Cloudflare is blocking the connection. In that case make sure your wings ip is added to the Cloudflare firewall. If you aren't using Cloudflare it might be some other CDN/ DDoS protection service or your provider. + * `Error response from Panel: AccessDeniedHttpException: You are not authorized to access this resource. (HTTP/403)`: Your wings token is wrong, you need to [update the token in your config.yml file](./wings/install/standalone#configure) + * `Error response from Panel: _MissingResponseCode: No error response returned from API endpoint`: Your panel is not responding correctly. This usually happens when Cloudflare is blocking the connection. In that case make sure your wings ip is added to the Cloudflare firewall. If you aren't using Cloudflare it might be some other CDN/DDoS protection service or your provider. * `remote: could not unmarshal response: invalid character '<' looking for beginning of value`: This is basically the same error as above: Cloudflare is blocking the connection.
### Check the wings port -If you confirmed that wings is running without errors you should make sure that the wings port (`8080` by default) isn't blocked by any firewall. The best way to check this is to use online port checkers like [dnschecker.org](https://dnschecker.org/port-scanner.php) +If you confirmed that wings is running without errors you should make sure that the wings port (`8080` by default) isn't blocked by any firewall. The best way to check this is to use online port checkers like [dnschecker.org](https://dnschecker.org/port-scanner.php). It should say "open" if you check for your node FQDN (e.g. `node.example.com` or `123.123.123.123`) and your wings port (e.g. `8080`). If it says "timed-out" you have some firewall blocking the port. This could be an internal firewall (like iptables) or an external firewall (e.g. from your provider). ### Check for NAT loop back If your panel and wings are on the same machine or same network, and you are using domains you should check for NAT loop back issues. -Edit the `/etc/hosts` file on your panel/ wings machine and add an entry for your ip and domain. +Edit the `/etc/hosts` file on your panel/wings machine and add an entry for your ip and domain. Example: @@ -104,15 +104,15 @@ In both cases it should output this when wings is reachable: {"error" : "The required authorization heads were not present in the request."} ``` - +:::info Not sure what a specific error means? Visit our [Discord](https://discord.gg/pelican-panel) and we will be happy to help you! - +::: ### Check node settings -If the connection checks above were both successfull you might have misconfigured the Node settings in the Panel. -Make sure that your Node FQDN/ IP, Port and Scheme (HTTP/ HTTPS) is correct. +If the connection checks above were both successful you might have misconfigured the Node settings in the Panel. +Make sure that your Node FQDN/IP, Port and Scheme (HTTP/HTTPS) is correct. When using a reverse proxy you might have different external and internal ports for Wings. (e.g. `80` internally and `443` externally) In that case make sure the Node settings in the Panel uses the external port while the Wings config file uses the internal port! @@ -124,7 +124,7 @@ If your Schedules are stuck on `Processing` or don't execute the tasks check the * Is your Schedule set to run `ONLY WHEN SERVER IS ONLINE` and the server is currently offline? * Is your queue worker service running? (`systemctl status pelican-queue`) * Is your queue worker service using the correct PHP version? (`php -v`) -* Is your cronjob setup correctly? `crontab -l -u www-data` (where `www-data` is your webserver user) should show the following entry: +* Is your cronjob setup correctly? `crontab -l -u www-data` (where `www-data` is your web server user) should show the following entry: `* * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1` If your queue worker service is not running you can also check the panel logs for errors. @@ -140,6 +140,6 @@ To recreate the queue worker service you can run `php /var/www/pelican/artisan p If a file upload form returns an error like `mountedActionsData.0.files.24d4b82d-a3ae-47fd-981f-8b2f0f6a21d4` it is most likely a proxy issue. Make sure your `Trusted Proxies` are set to the correct ips, both in the panel settings and your proxy settings! -Also make sure your webserver and/ or proxy have a high enough upload limit. (e.g. `client_max_body_size`, `upload_max_filesize` and `post_max_size`) +Also make sure your web server and/or proxy have a high enough upload limit. (e.g. `client_max_body_size`, `upload_max_filesize` and `post_max_size`) In some cases the issue can also be caused by incorrect file permissions. See [above](#wrong-file-permissions) on how to fix your file permissions. diff --git a/docs/wings/install.mdx b/docs/wings/install.mdx deleted file mode 100644 index 32894926..00000000 --- a/docs/wings/install.mdx +++ /dev/null @@ -1,137 +0,0 @@ -import Admonition from '@theme/Admonition'; - -# Installing Wings - - -This software will not work on Windows operating systems. - - - - It is always recommended to keep the server files on a separate partition. - This prevents the root partition from filling and causing the host to crash, potentially becoming unbootable. - - -## Supported Systems - -The following is a list of supported operating systems. Please be aware that this is not an exhaustive list, -there is a high probability that you can run the software on other Linux distributions without much effort. -You are responsible for determining which packages may be necessary on those systems. There is also a very -high probability that new releases of the supported OSes below will work just fine, you are not restricted to -only the versions listed below. - -| Operating System | Version | Supported | Notes | -|:----------------:|:--------:|:---------:|:---------------------------------------------------------------------:| -| **Ubuntu** | 22.04 | ✅︎︎ | | -| | **24.04**| ✅︎ | Documentation written assuming Ubuntu 24.04 as the base OS. | -| **Alma Linux** | 10 | ✅︎ | | -| | 9 | ✅︎ | | -| | 8 | ✅︎ | | -| **Rocky Linux** | 9 | ✅︎ | | -| | 8 | ✅︎ | | -| **CentOS** | 10 | ✅︎ | | -| **Debian** | 11 | ✅︎ | | -| | 12 | ✅︎ | | - -## System Requirements - - - Please be aware that some hosts install a modified kernel that does not support some docker features required for Wings to operate correctly. Please - check your kernel by running `uname -r`. If your kernel ends in `-xxxx-grs-ipv6-64` or `-xxxx-mod-std-ipv6-64` you're - probably using a non-supported kernel. You should contact your host, and request a non-modified kernel. - - -To run Wings, you will need a Linux system capable of running Docker containers. Most VPS and almost all -dedicated servers should be capable of running Docker, but there are edge cases. - -When your provider uses `Virtuozzo`, `OpenVZ` (or `OVZ`), or `LXC` virtualization, you will most likely be unable to -run Wings. Some providers have made the necessary changes for nested virtualization to support Docker. Ask your provider's support team to make sure. KVM is guaranteed to work. - -The easiest way to check is to type `systemd-detect-virt`. -If the result doesn't contain `OpenVZ` or`LXC`, it should be fine. The result of `none` will appear when running dedicated hardware without any virtualization. - -Should that not work for some reason, or you're still unsure, you can also run the command below. - -```sh -sudo dmidecode -s system-manufacturer -``` - -### Installing Docker -Wings requires Docker CE. For full instructions on installing and configuring Docker, see the [installation guide](/docs/guides/docker). - -For a quick install of Docker CE, you can use the command below: - -```sh -curl -sSL https://get.docker.com/ | CHANNEL=stable sudo sh -``` - -### Installing Wings - -The first step for installing Wings is to ensure we have the required directory structure setup. To do so, -run the commands below, which will create the base directory and download the wings executable. - -```sh -sudo mkdir -p /etc/pelican /var/run/wings -sudo curl -L -o /usr/local/bin/wings "https://github.com/pelican-dev/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")" -sudo chmod u+x /usr/local/bin/wings -``` - -### Configure - -Once you have installed Wings and the required components, the next step is to create a node on your installed Panel. -Go to your Panel administrative view, select Nodes from the sidebar, and on the right side click Create New button. - -After you have created a node, click on it and there will be a tab called Configuration. -Copy the code block content, create a new file at `/etc/pelican/config.yml`, paste the content into it and save. - -Alternatively, you can click on the Auto Deploy Command button, copy the sh command and paste it into your terminal. - - - If your Panel is using SSL, then Wings must also use SSL. - - See [Creating SSL Certificates](../guides/ssl) documentation page for how to create these certificates before continuing. - - -### Starting Wings - -To start Wings, simply run the command below, which will start it in a debug mode. -Once you confirmed that it is running without errors, use `CTRL+C` to terminate the process and daemonize it by following the instructions below. -Depending on your server's internet connection pulling and starting Wings for the first time may take a few minutes. - -```sh -sudo wings --debug -``` - -You may optionally add the `--debug` flag to run Wings in debug mode. - -### Daemonizing (using systemd) - -Running Wings in the background is a simple task, just make sure that it runs without errors before doing -this. Place the contents below in a file called `wings.service` in the `/etc/systemd/system` directory. - -```ini {9} title="/etc/systemd/system/wings.service" -[Unit] -Description=Wings Daemon -After=docker.service -Requires=docker.service -PartOf=docker.service - -[Service] -User=root -WorkingDirectory=/etc/pelican -LimitNOFILE=4096 -PIDFile=/var/run/wings/daemon.pid -ExecStart=/usr/local/bin/wings -Restart=on-failure -StartLimitInterval=180 -StartLimitBurst=30 -RestartSec=5s - -[Install] -WantedBy=multi-user.target -``` - -Then, run the commands below to reload systemd and start Wings. - -```sh -sudo systemctl enable --now wings -``` diff --git a/docs/wings/install/dockerized.mdx b/docs/wings/install/dockerized.mdx new file mode 100644 index 00000000..4be4fee7 --- /dev/null +++ b/docs/wings/install/dockerized.mdx @@ -0,0 +1,90 @@ +--- +pagination_prev: null +pagination_next: null +--- + +# Dockerized installation + +Run the Wings Daemon inside a docker container. + +:::danger + **You should have some basic familiarity with Docker before you proceed!** +::: + +Pelican provides pre-built Docker images via GitHub Packages. `ghcr.io/pelican-dev/wings:latest` is the current latest release, and `ghcr.io/pelican-dev/wings:main` is built automatically from the current `main` branch. + +## Install Docker + +For a quick install of Docker CE, you can use the command below: + +```sh +curl -sSL https://get.docker.com/ | CHANNEL=stable sudo sh +``` + +:::info[Trouble installing?] + 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. +::: + +### Start Docker on Boot + +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. + +```sh +sudo systemctl enable --now docker +``` + +## Setup compose file + +The easiest deployment method is using the standard `compose.yml` file. + +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). + +### Create compose.yml + +```yml title="compose.yml" +services: + wings: + image: ghcr.io/pelican-dev/wings:latest + restart: always + networks: + - wings0 + ports: + - "8080:8080" + - "2022:2022" + tty: true + environment: + TZ: "UTC" + WINGS_UID: 988 + WINGS_GID: 988 + WINGS_USERNAME: pelican + volumes: + - "/var/run/docker.sock:/var/run/docker.sock" + - "/var/lib/docker/containers/:/var/lib/docker/containers/" + - "/etc/pelican/:/etc/pelican/" + - "/var/lib/pelican/:/var/lib/pelican/" + - "/var/log/pelican/:/var/log/pelican/" + - "/tmp/pelican/:/tmp/pelican/" + - "/etc/ssl/certs:/etc/ssl/certs:ro" + # you may need /srv/daemon-data if you are upgrading from an old daemon + #- "/srv/daemon-data/:/srv/daemon-data/" + # Required for ssl if you use let's encrypt. uncomment to use. + #- "/etc/letsencrypt/:/etc/letsencrypt/" + +networks: + wings0: + name: wings0 + driver: bridge + ipam: + config: + - subnet: "172.21.0.0/16" + driver_opts: + com.docker.network.bridge.name: wings0 +``` + +## Start the container + +From the directory in which the compose file is located, run: + +```sh +docker compose up -d +``` \ No newline at end of file diff --git a/docs/wings/install/standalone.mdx b/docs/wings/install/standalone.mdx new file mode 100644 index 00000000..c380bbf4 --- /dev/null +++ b/docs/wings/install/standalone.mdx @@ -0,0 +1,120 @@ +--- +pagination_prev: null +pagination_next: null +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Standalone installation + +Run the Wings Daemon directly on a linux server. + +:::danger + **You should have some basic familiarity with Linux before you proceed!** +::: + +## System Requirements + +:::warning + Please be aware that some hosts install a modified kernel that does not support some docker features required for Wings to operate correctly. + Please check your kernel by running `uname -r`. If your kernel ends in `-xxxx-grs-ipv6-64` or `-xxxx-mod-std-ipv6-64` you're probably using a non-supported kernel. You should contact your host, and request a non-modified kernel. +::: + +To run Wings, you will need a Linux system capable of running Docker containers. Most VPS and almost all +dedicated servers should be capable of running Docker, but there are edge cases. + +When your provider uses `Virtuozzo`, `OpenVZ` (or `OVZ`), or `LXC` virtualization, you will most likely be unable to +run Wings. Some providers have made the necessary changes for nested virtualization to support Docker. Ask your provider's support team to make sure. KVM is guaranteed to work. + +The easiest way to check is to type `systemd-detect-virt`. +If the result doesn't contain `OpenVZ` or `LXC`, it should be fine. The result of `none` will appear when running dedicated hardware without any virtualization. + +Should that not work for some reason, or you're still unsure, you can also run the command below. + +```sh +sudo dmidecode -s system-manufacturer +``` + +## Installing Docker + +Wings requires Docker CE. For a quick install of Docker CE, you can use the command below: + +```sh +curl -sSL https://get.docker.com/ | CHANNEL=stable sudo sh +``` + +:::info[Trouble installing?] + 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. +::: + +## Download Wings binary + +The first step for installing Wings is to ensure we have the required directory structure setup. To do so, run the commands below, which will create the base directory and download the wings executable. + +```sh +sudo mkdir -p /etc/pelican /var/run/wings +sudo curl -L -o /usr/local/bin/wings "https://github.com/pelican-dev/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")" +sudo chmod u+x /usr/local/bin/wings +``` + +## Configure + +Once you have installed Wings and the required components, the next step is to create a node on your installed Panel. +Go to your Panel administrative view, select Nodes from the sidebar, and on the right side click Create New button. + +After you have created a node, click on it and there will be a tab called Configuration. +Copy the code block content, create a new file at `/etc/pelican/config.yml`, paste the content into it and save. + +Alternatively, you can click on the Auto Deploy Command button, copy the sh command and paste it into your terminal. + +:::warning[Using ssl?] + If your Panel is using SSL, Wings must also use SSL. + + See [Creating SSL Certificates](../../guides/ssl) documentation page for how to create these certificates before continuing. +::: + +## Starting Wings for the first time + +To start Wings for the first time, simply run the command below, which will start it in a debug mode. +Once you confirmed that it is running without errors, use `CTRL+C` to terminate the process and daemonize it by following the instructions below. + +Depending on your server's internet connection pulling and starting Wings for the first time may take a few minutes. + +```sh +sudo wings --debug +``` + +## Daemonizing (using systemd) + +Running Wings in the background is a simple task, just make sure that it runs without errors before doing this. + +Place the contents below in a file called `wings.service` in the `/etc/systemd/system` directory. + +```ini {9} title="/etc/systemd/system/wings.service" +[Unit] +Description=Wings Daemon +After=docker.service +Requires=docker.service +PartOf=docker.service + +[Service] +User=root +WorkingDirectory=/etc/pelican +LimitNOFILE=4096 +PIDFile=/var/run/wings/daemon.pid +ExecStart=/usr/local/bin/wings +Restart=on-failure +StartLimitInterval=180 +StartLimitBurst=30 +RestartSec=5s + +[Install] +WantedBy=multi-user.target +``` + +Then, run the command below to start Wings and enable start on boot. + +```sh +sudo systemctl enable --now wings +``` \ No newline at end of file diff --git a/docs/wings/optional-config.mdx b/docs/wings/optional-config.mdx index 43b6ebce..1c07a708 100644 --- a/docs/wings/optional-config.mdx +++ b/docs/wings/optional-config.mdx @@ -1,11 +1,8 @@ -import Admonition from '@theme/Admonition'; - # Additional Configuration - -These are advanced configurations for Wings. You risk breaking Wings and making containers unusable if -you misconfigure something. Proceed only if you know what each configuration value does. - +:::danger + These are advanced configurations for Wings. You risk breaking Wings and making containers unusable if you misconfigure something. Proceed only if you know what each configuration value does. +::: You must apply all changes to your Wings `config.yml` file located at `/etc/pelican` and restart wings. Verify your config file using [Yaml Lint](http://www.yamllint.com/) should you receive errors related to YAML parsing. @@ -36,9 +33,9 @@ docker: You can change the network interface that Wings uses for all containers by editing the network name; it is by default set to `pelican_nw`. For example, to enable Docker host mode change the network name to `host`. - - Changing network mode to `host` grants Pelican direct access to all machine interfaces and Panel users can bind to any IP or Port even if it's not allocated to their container. You will lose all benefits of Docker network isolation. It is not recommended for public installations that are hosting other users' servers. - +:::warning + Changing network mode to `host` grants Pelican direct access to all machine interfaces and Panel users can bind to any IP or Port even if it's not allocated to their container. You will lose all benefits of Docker network isolation. It is not recommended for public installations that are hosting other users' servers. +::: ### Example of usage @@ -152,4 +149,4 @@ More commonly discussed values. | websocket_log_count | 150 | The number of lines to display in the console | | detect_clean_exit_as_crash | true | Mark server as crashed if it's stopped without user interaction, e.g., not pressing stop button | | (crash detection) timeout | 60 | Timeout between server crashes that will not cause the server to be automatically restarted | -| check_permissions_on_boot | true | Check all file permissions on each boot. Disable this when you have a very large amount of files and the server startup is hanging on checking permissions | +| check_permissions_on_boot | true | Check all file permissions on each boot. Disable this when you have a very large amount of files and the server startup is hanging on checking permissions | \ No newline at end of file diff --git a/docs/wings/update.mdx b/docs/wings/update.mdx index ccc1e62f..6d96b974 100644 --- a/docs/wings/update.mdx +++ b/docs/wings/update.mdx @@ -1,47 +1,47 @@ -import Admonition from '@theme/Admonition'; +--- +pagination_prev: null +pagination_next: null +--- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Updating Wings +# Update -Updating Wings is a painless process and should take less than a minute to complete. +A brief guide on how to update the Wings Daemon to the latest version. ## Wings Version Requirements | Panel Version | Wings Version | Supported | |:-------------:|:-------------:|:---------:| -|1.0.0+ | 1.0.0+ | ✅︎ | +|1.0.0+ | 1.0.0+ | ✅︎ | ## Download Update - - Running servers **will not** be affected. - +:::tip + Updating Wings **will not** affect running (game-) servers. +::: - First, you need to run the Wings auto-updater, which is included starting from **beta9**. + Since **beta9** Wings includes a self updater. Simply run the following commands to update: ```sh sudo wings update + + sudo systemctl restart wings ``` - First, download the updated wings binary into `/usr/local/bin`. You will need to stop Wings briefly. + Manually updating Wings is very simple. Briefly stop the Wings service, download the new Wings release and start the service again: ```sh sudo systemctl stop wings + sudo curl -L -o /usr/local/bin/wings "https://github.com/pelican-dev/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")" sudo chmod u+x /usr/local/bin/wings + + sudo systemctl restart wings ``` - - -## Restart - -Secondly, Restart the process. - -```sh -sudo systemctl restart wings -``` diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 5156b8d2..cca4a863 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -72,11 +72,11 @@ const config: Config = { items: [ { label: 'Panel', - to: '/docs/panel/getting-started', + to: '/docs/category/panel', }, { label: 'Wings', - to: '/docs/wings/install', + to: '/docs/category/wings', }, { label: 'SSL Setup', diff --git a/sidebars.ts b/sidebars.ts index c2e0ad7f..8c0a1933 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -16,63 +16,102 @@ const sidebars: SidebarsConfig = { { type: 'category', label: 'Panel', - collapsed: false, + link: { + type: 'generated-index', + description: 'The Panel is a Laravel web application that serves as the web interface for users.', + }, + collapsible: false, items: [ - 'panel/getting-started', - 'panel/webserver-config', - 'panel/panel-setup', - 'panel/optional-config', + { + type: 'category', + label: 'Installation', + link: { + type: 'generated-index', + slug: '/category/panel-installation', + description: 'You can choose between two installation methods:', + }, + items: [ + 'panel/install/standalone', + 'panel/install/dockerized', + ], + }, 'panel/update', + 'panel/optional-config', { type: 'category', label: 'Advanced', + link: { + type: 'generated-index', + }, items: [ - 'panel/advanced/redis', 'panel/advanced/mysql', - 'panel/advanced/artisan', - 'panel/advanced/docker', - 'panel/advanced/plugins', - ] - } + 'panel/advanced/redis', + ], + }, + 'panel/plugins' ], }, { type: 'category', label: 'Wings', + link: { + type: 'generated-index', + description: 'Wings is the backend service installed on one or more node machines and acts as the interface between Docker and the Panel.', + }, + collapsible: false, items: [ - 'wings/install', + { + type: 'category', + label: 'Installation', + link: { + type: 'generated-index', + slug: '/category/wings-installation', + description: 'You can choose between two installation methods:', + }, + items: [ + 'wings/install/standalone', + 'wings/install/dockerized', + ], + }, + 'wings/update', 'wings/optional-config', - 'wings/update' - ], - }, - { - type: 'category', - label: 'Eggs', - items: [ - 'eggs/creating-a-custom-egg', - 'eggs/creating-a-custom-yolk', ], }, { type: 'category', label: 'Guides', + link: { + type: 'generated-index', + }, items: [ - 'guides/docker', - 'guides/mounts', 'guides/ssl', + 'guides/mounts', 'guides/php-upgrade', 'guides/database-hosts', 'guides/change-panel-domain', 'guides/uninstalling', - + { + type: 'category', + label: 'Eggs', + link: { + type: 'generated-index', + }, + items: [ + 'guides/eggs/creating-a-custom-egg', + 'guides/eggs/creating-a-custom-yolk', + ], + }, { type: 'category', label: 'Disk Quotas', + link: { + type: 'doc', + id: 'guides/disk-quotas/index', + }, items: [ - 'guides/disk-quotas/about', 'guides/disk-quotas/ext4-xfs', - ] - } + ], + }, ], }, 'troubleshooting', diff --git a/src/pages/faq.mdx b/src/pages/faq.mdx index 9daa1a58..c7d67a5e 100644 --- a/src/pages/faq.mdx +++ b/src/pages/faq.mdx @@ -1,7 +1,5 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import Admonition from '@theme/Admonition'; - # Frequently Asked Questions @@ -9,10 +7,10 @@ Here are some of the most asked questions and our answers. **Last Updated: 2026-03-12** - +:::info[When is the beta?] The Beta is now available! - **Head over to the [Install docs](/docs/panel/getting-started) and try out Pelican yourself.** - + **Head over to the [Install docs](/docs) and try out Pelican yourself.** +::: @@ -82,7 +80,7 @@ Here are some of the most asked questions and our answers. We are working on adding new features and improvements to Wings that will greatly improve your experience.
- Will Podman / Kubernetes be supported? + Will Podman/Kubernetes be supported? Yes, we plan on supporting them in the future.
@@ -94,7 +92,7 @@ Here are some of the most asked questions and our answers. Plugins do _not_ fall under the new license because they do not modify the panel source code. See the [plugin FAQ](?faq=plugins) for more information. - + :::info[Summary] The license change does only affect you if you meet _all_ of the following requirements: 1. You modified the Pelican panel source files. 2. These modifications are not open source. @@ -102,7 +100,7 @@ Here are some of the most asked questions and our answers. If you meet _all_ of the above requirements you need a commercial license. **Please note that the usage or development of plugins/themes does not require a commercial license.** - + :::
@@ -162,19 +160,19 @@ Here are some of the most asked questions and our answers.
What can plugins do? - Pretty much anything you want! They can add new pages, change existing ones (to some extent), add new languages, change the theme (color/ font/ css) and more. + Pretty much anything you want! They can add new pages, change existing ones (to some extent), add new languages, change the theme (color/font/css) and more. The first iteration _will_ have some limitations but we will continuously improve the capabilities of plugins.
How are plugins installed? - You can find information on that [here](./docs/panel/advanced/plugins#install-a-plugin). + You can find information on that [here](./docs/panel/plugins#install-a-plugin).
How do you create plugins? - You can find detailed information on that [here](./docs/panel/advanced/plugins#create-a-plugin). + You can find detailed information on that [here](./docs/panel/plugins#create-a-plugin).
Are the plugins from the sneak peaks available? diff --git a/src/pages/index.tsx b/src/pages/index.tsx index b632ead6..7e84dbfd 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -1,4 +1,4 @@ -import React, {JSX} from 'react'; +import React, { JSX } from 'react'; import clsx from 'clsx'; import Link from '@docusaurus/Link'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; @@ -13,7 +13,7 @@ import { Icon } from '@iconify/react/dist/iconify.js'; import styles from './index.module.css'; function HomepageHeader() { - const {siteConfig} = useDocusaurusContext(); + const { siteConfig } = useDocusaurusContext(); return (
@@ -25,8 +25,8 @@ function HomepageHeader() { Install + to="/docs" + >Documentation