From d02eae88f9ea0575d36234cd913d074dfca21f84 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Wed, 25 Jun 2025 20:06:55 +0530 Subject: [PATCH 1/8] Install Plane with Podman Quadlets --- mint.json | 3 +- self-hosting/methods/podman-quadlets.mdx | 131 +++++++++++++++++++++++ 2 files changed, 133 insertions(+), 1 deletion(-) create mode 100644 self-hosting/methods/podman-quadlets.mdx diff --git a/mint.json b/mint.json index 291b4832..5a101da1 100644 --- a/mint.json +++ b/mint.json @@ -72,7 +72,8 @@ "self-hosting/methods/kubernetes", "self-hosting/methods/coolify", "self-hosting/methods/portainer", - "self-hosting/methods/airgapped-edition" + "self-hosting/methods/airgapped-edition", + "self-hosting/methods/podman-quadlets" ] }, { diff --git a/self-hosting/methods/podman-quadlets.mdx b/self-hosting/methods/podman-quadlets.mdx new file mode 100644 index 00000000..47df7dec --- /dev/null +++ b/self-hosting/methods/podman-quadlets.mdx @@ -0,0 +1,131 @@ +--- +title: Deploy Plane with Podman Quadlets • Commercial Edition +sidebarTitle: Podman Quadlets +--- + +This guide shows you the steps to deploy a self-hosted instance of Plane using Podman Quadlets. + +## Prerequisites +Before we start, make sure you've got these covered: + +- A non-root user account with `systemd --user support` (most modern Linux setups have this) +- Podman version **4.4 or higher** + +## Set up Podman +1. Add the Podman repository. + ```bash + echo 'deb http://download.opensuse.org/repositories/home:/alvistack/Debian_12/ /' | sudo tee /etc/apt/sources.list.d/home:alvistack.list + ``` + +2. Add the GPG key. + ```bash + curl -fsSL https://download.opensuse.org/repositories/home:alvistack/Debian_12/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_alvistack.gpg > /dev/null + ``` + +3. Refresh your package lists + ```bash + sudo apt update + ``` + +4. Install Podman and its dependencies. + ```bash + sudo apt install -y podman uidmap netavark passt + ``` + + The `uidmap` package handles user namespace mapping, `netavark` takes care of networking, and `passt` helps with network connectivity. + +5. Download and extract Podman Quadlets. + ```bash + tar -xzf podman-quadlets.tar.gz + cd podman-quadlets + ``` + + The directory contains an `install.sh` script that will handle the installation and configuration. + +## Install Plane + +The installation script sets up Plane and configures all required services. You have two options: + +### Without sudo access + ```bash + ./install.sh --domain your-domain.com --base-dir /your/custom/path + ``` + This installs Plane in your specified directory, which is useful if you want to maintain control over the installation location. + +### With sudo access + ```bash + ./install.sh --domain your-domain.com + ``` + This installs Plane in `/opt/plane`, which is a standard system location. + + +Systemd configurations are installed in `~/.config/containers/systemd/` + + +## Start Plane + + +**Important** +Note that you should run these commands without `sudo`. + + +1. Reload systemd to recognize new configurations. + ```bash + systemctl --user daemon-reload + ``` + +2. Start the network service. + ```bash + systemctl --user start plane-nw-network.service + ``` + +3. Start core dependencies. + ```bash + systemctl --user start plane-{db,redis,mq,minio}.service + ``` + +4. Start backend services. + ```bash + systemctl --user start {api,worker,beat-worker,migrator,monitor}.service + ``` + +5. Start frontend services. + ```bash + systemctl --user start {web,space,admin,live,proxy}.service + ``` + +The startup sequence is important: network first, then dependencies, followed by backend services, and finally frontend services. + +### Verify service status +Check that all services are running correctly: + +1. Check network status. + ```bash + systemctl --user status plane-nw-network.service + ``` + +2. Check core dependencies. + ```bash + systemctl --user status plane-{db,redis,mq,minio}.service + ``` + +3. Check backend services + ```bash + systemctl --user status {api,worker,beat-worker,migrator,monitor}.service + ``` + +4. Check frontend services. + ```bash + systemctl --user status {web,space,admin,live,proxy}.service + ``` + +Your Plane installation should now be running successfully with Podman Quadlets. This setup provides automatic service restart capabilities and standard systemd management commands for maintaining your installation. + +## Troubleshoot + +To debug service issues, examine the logs using: + ```bash + journalctl --user -u --no-pager + ``` + +The logs will provide detailed information about any configuration issues or errors that may occur. From 5baaefc3d3d3168d08482f856847c1ea4215e723 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Wed, 25 Jun 2025 20:12:20 +0530 Subject: [PATCH 2/8] minor fixes --- self-hosting/methods/podman-quadlets.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/self-hosting/methods/podman-quadlets.mdx b/self-hosting/methods/podman-quadlets.mdx index 47df7dec..4c41a9c8 100644 --- a/self-hosting/methods/podman-quadlets.mdx +++ b/self-hosting/methods/podman-quadlets.mdx @@ -22,7 +22,7 @@ Before we start, make sure you've got these covered: curl -fsSL https://download.opensuse.org/repositories/home:alvistack/Debian_12/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_alvistack.gpg > /dev/null ``` -3. Refresh your package lists +3. Refresh your package lists. ```bash sudo apt update ``` @@ -109,7 +109,7 @@ Check that all services are running correctly: systemctl --user status plane-{db,redis,mq,minio}.service ``` -3. Check backend services +3. Check backend services. ```bash systemctl --user status {api,worker,beat-worker,migrator,monitor}.service ``` @@ -118,7 +118,7 @@ Check that all services are running correctly: ```bash systemctl --user status {web,space,admin,live,proxy}.service ``` - + Your Plane installation should now be running successfully with Podman Quadlets. This setup provides automatic service restart capabilities and standard systemd management commands for maintaining your installation. ## Troubleshoot From 59d36194c7cd063becd20515d412cd0d93a50c36 Mon Sep 17 00:00:00 2001 From: Aaron Heckmann Date: Wed, 9 Jul 2025 00:45:05 -0700 Subject: [PATCH 3/8] [DOCSW-418] Dev improvements #120 --- .github/workflows/ci.yml | 32 ++++++++++++++++++++++ CONTRIBUTING.md | 24 ++++++++++++---- self-hosting/govern/github-oauth.mdx | 1 - self-hosting/govern/google-oauth.mdx | 4 +-- self-hosting/methods/airgapped-edition.mdx | 2 +- 5 files changed, 52 insertions(+), 11 deletions(-) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..94ef4649 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,32 @@ +name: CI +on: pull_request + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + ci: + name: Test + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 2 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + + - name: Check for broken links + run: | + set -e + output=$(npx mint broken-links) + echo "$output" + if ! echo "$output" | grep -q '^success '; then + echo "Error: Broken links found! Fix the broken links listed above before merging." + exit 1 + fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f50d7819..51e6954d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,10 +17,22 @@ git checkout -b ### 3. Make Changes in the Appropriate Page Navigate to the relevant documentation page in the repository and make your changes. Ensure that your changes align with our style guide and maintain consistency across the documentation. -### 4. Raise a Pull Request (PR) +### 4. Preview your changes +Make sure you are visually happy with your changes. + +1. Run `npx mint dev` +1. A url will be printed to your console. Open it in your browser. +1. Visit your pages and confirm they look correct. + +### 5. Fix broken links + +1. Run `npx mint broken-links` +2. Fix all reported broken links + +### 6. Raise a Pull Request (PR) Once your changes are ready, raise a pull request (PR) to merge your branch into the `master` branch. Please provide a descriptive title and detailed description of your changes. -### 5. Leave a Clear Commit Message +### 7. Leave a Clear Commit Message When committing your changes, leave a clear and concise message that links to the corresponding issue (if applicable) and explains the fix or enhancement you've made. ```bash @@ -28,13 +40,13 @@ git add . git commit -m "Fixes #: Description of the fix or enhancement" ``` -### 6. Link the Issue to the Pull Request +### 8. Link the Issue to the Pull Request In your pull request description, be sure to reference the related issue using GitHub's syntax (`#`). This links the PR to the issue and helps maintain context. -### 7. Sign the Contributor License Agreement (CLA) +### 9. Sign the Contributor License Agreement (CLA) Before we can merge your contribution, you must sign our contributor license agreement (CLA). This agreement ensures that your contributions comply with our licensing terms. -### 8. Assign a Reviewer from Our Team +### 10. Assign a Reviewer from Our Team Once your PR is submitted, a member of our team will be assigned to review your changes. They will provide feedback and may request revisions if necessary. Please respond promptly to any review comments to expedite the merging process. -Thank you for contributing to our documentation! We appreciate your efforts in making our product documentation more comprehensive and user-friendly. If you have any questions or need assistance, feel free to reach out to our team. Happy contributing! \ No newline at end of file +Thank you for contributing to our documentation! We appreciate your efforts in making our product documentation more comprehensive and user-friendly. If you have any questions or need assistance, feel free to reach out to our team. Happy contributing! diff --git a/self-hosting/govern/github-oauth.mdx b/self-hosting/govern/github-oauth.mdx index 096268d5..f5e141de 100644 --- a/self-hosting/govern/github-oauth.mdx +++ b/self-hosting/govern/github-oauth.mdx @@ -25,6 +25,5 @@ Plane also supports GitHub OAuth so your users can sign-in with GitHub instead. 1. Go to `GitHub` on the Authentication screen of `/god mode`. 2. Add the client ID + the client secret from the GitHub app you just registered. 3. Click `Save `. -![](/images/instance-admin/authentication-instance-settings.png) Your Plane instance should now work with GitHub sign-in. diff --git a/self-hosting/govern/google-oauth.mdx b/self-hosting/govern/google-oauth.mdx index e275bdba..8f1183b3 100644 --- a/self-hosting/govern/google-oauth.mdx +++ b/self-hosting/govern/google-oauth.mdx @@ -29,10 +29,8 @@ First, you will need to identify Plane as an approved OAuth app to Google. 1. Go to `Google` on the Authentication screen of `/god mode`. 2. Add the client ID + the client secret from Google API Console. 3. Click `Save `. -![](/images/instance-admin/authentication-instance-settings.png) - Your Plane instance should now work with `Sign in with Google`. -We don't restrict domains in with Google OAuth yet. It's on our roadmap. \ No newline at end of file +We don't restrict domains in with Google OAuth yet. It's on our roadmap. diff --git a/self-hosting/methods/airgapped-edition.mdx b/self-hosting/methods/airgapped-edition.mdx index 29844818..d5f4844e 100644 --- a/self-hosting/methods/airgapped-edition.mdx +++ b/self-hosting/methods/airgapped-edition.mdx @@ -165,7 +165,7 @@ Once your air-gapped installation is running, you'll need to activate your works You should have received the `license_key.json` file as part of your air-gapped package. If you don't have this file, contact our support team. -1. Go to your [Workspace Settings](/core-concepts/workspaces/overview#workspace-settings) in the Plane application. +1. Go to your [Workspace Settings](https://docs.plane.so/core-concepts/workspaces/overview#workspace-settings) in the Plane application. 2. Select **Billing and plans** on the right pane. 3. Click the **Activate this workspace** button. ![Upload license file](/images/activate-license/upload-airgapped-license-file.webp) From 5a6562a68b0887a7f03fe3ec4128cd33c6694a4c Mon Sep 17 00:00:00 2001 From: Aaron Heckmann Date: Wed, 9 Jul 2025 09:51:05 -0700 Subject: [PATCH 4/8] chore: trigger CI From 69636b7b172e987deeabd1cafe6b3dad4005ad1f Mon Sep 17 00:00:00 2001 From: Srinivas Pendem Date: Mon, 14 Jul 2025 16:17:05 +0530 Subject: [PATCH 5/8] updating the Prerequisites for docker compose --- self-hosting/methods/docker-compose.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/self-hosting/methods/docker-compose.mdx b/self-hosting/methods/docker-compose.mdx index 8a115c79..0f6a5f5a 100644 --- a/self-hosting/methods/docker-compose.mdx +++ b/self-hosting/methods/docker-compose.mdx @@ -9,7 +9,7 @@ Plane One and Plane Pro are enabled on this edition, so the Free plan on this ed ### Prerequisites - - A virtual or on-prem machine with atleast 2 vCPUs and 4 GB RAM + - A virtual or on-prem machine with at least 4 vCPUs and 16 GB RAM - `x64` AKA `AMD 64` or `AArch 64` AKA `ARM 64` CPUs - Supported operating systems: - Ubuntu From b910336ca3f3a05a2f3141b3b509698c14114c90 Mon Sep 17 00:00:00 2001 From: srinivas pendem <65014795+srinivaspendem@users.noreply.github.com> Date: Mon, 14 Jul 2025 21:19:40 +0530 Subject: [PATCH 6/8] Update docker-compose.mdx --- self-hosting/methods/docker-compose.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/self-hosting/methods/docker-compose.mdx b/self-hosting/methods/docker-compose.mdx index 0f6a5f5a..5cc9a79b 100644 --- a/self-hosting/methods/docker-compose.mdx +++ b/self-hosting/methods/docker-compose.mdx @@ -9,7 +9,7 @@ Plane One and Plane Pro are enabled on this edition, so the Free plan on this ed ### Prerequisites - - A virtual or on-prem machine with at least 4 vCPUs and 16 GB RAM + - A virtual or on-prem machine with at least 2 vCPUs and 8 GB RAM - `x64` AKA `AMD 64` or `AArch 64` AKA `ARM 64` CPUs - Supported operating systems: - Ubuntu @@ -136,4 +136,4 @@ If you want to upgrade to a paid plan, see [Plan upgrades](https://docs.plane.so ## Troubleshoot - [Error during Docker Compose execution](/self-hosting/troubleshoot/installation-errors#error-during-docker-compose-execution) -- [Migrator container exited](/self-hosting/troubleshoot/installation-errors#migrator-container-exited) \ No newline at end of file +- [Migrator container exited](/self-hosting/troubleshoot/installation-errors#migrator-container-exited) From 923da860a26cc982e5132f7770171eb5c17f9629 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Mon, 21 Jul 2025 15:44:57 +0530 Subject: [PATCH 7/8] Merge branch 'preview' of github.com:makeplane/developer-docs into podman-quadlets From c44861f205d8d6c3d949c46e28a900369344a43c Mon Sep 17 00:00:00 2001 From: danciaclara Date: Mon, 21 Jul 2025 15:52:12 +0530 Subject: [PATCH 8/8] minor fix --- self-hosting/methods/docker-compose.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/self-hosting/methods/docker-compose.mdx b/self-hosting/methods/docker-compose.mdx index 5cc9a79b..7639aeee 100644 --- a/self-hosting/methods/docker-compose.mdx +++ b/self-hosting/methods/docker-compose.mdx @@ -9,7 +9,7 @@ Plane One and Plane Pro are enabled on this edition, so the Free plan on this ed ### Prerequisites - - A virtual or on-prem machine with at least 2 vCPUs and 8 GB RAM + - A virtual or on-prem machine with at least 2 vCPUs and 4 GB RAM (8 GB RAM recommended) - `x64` AKA `AMD 64` or `AArch 64` AKA `ARM 64` CPUs - Supported operating systems: - Ubuntu