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/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/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) diff --git a/self-hosting/methods/docker-compose.mdx b/self-hosting/methods/docker-compose.mdx index 8a115c79..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 atleast 2 vCPUs and 4 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 @@ -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) diff --git a/self-hosting/methods/podman-quadlets.mdx b/self-hosting/methods/podman-quadlets.mdx new file mode 100644 index 00000000..4c41a9c8 --- /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.