Skip to content

Commit 9d46e84

Browse files
aheckmannaheckmann
committed
chore: add old plane-one docs
these were not live on the previous site so not making them live here just yet.
1 parent 9fd4d5e commit 9d46e84

File tree

9 files changed

+689
-0
lines changed

9 files changed

+689
-0
lines changed

‎old/plane-one/governance/authentication/custom-sso.mdx

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: OIDC and SAML
3+
sidebarTitle: Custom SSO
4+
---
5+
Plane One enables custom SSO via any identity provider with an official and supported implementation of OIDC + SAML standards. This page cites examples from Okta, but we will soon publish provider-specific instructions in phases.
6+
7+
## OIDC
8+
9+
You will need to configure values on your IdP first and then on Plane later.
10+
11+
### On your preferred IdP
12+
13+
Create a Plane client or application per your IdP's documentation and configure ↓.
14+
15+
<Tip>
16+
`domain.tld` is the domain that you have hosted your Plane app on.
17+
</Tip>
18+
19+
| **Config** | **Key** |
20+
|----------------|-------------------------------------------------------|
21+
| Origin URL | `http(s)://domain.tld/auth/oidc/` |
22+
| Callback URL | `http(s)://domain.tld/auth/oidc/callback/` |
23+
| Logout URL | `http(s)://domain.tld/auth/oidc/logout/` |
24+
25+
### On Plane
26+
27+
Go to `/god-mode/authentication/oidc` on your Plane app and find the configs ↓.
28+
29+
<Tip>
30+
Your IdP will generate some of the following configs for you. Others, you will specify yourself. Just copy them over to each field.
31+
</Tip>
32+
33+
<Frame>![OIDC Configuration](/images/custom-sso/oidc-config.png)</Frame>
34+
35+
- Copy the `CLIENT_ID` for the Plane client or app you just created over from your IdP and paste it in the field for it.
36+
37+
With providers like Keycloak, you have to choose a unique ID per app your configure. With providers like Okta and Auth0, you copy over the generated ID over to Plane. Typically, you will find it on the Plane application Home or Settings page on your IdP.
38+
39+
- Copy the `CLIENT_SECRET` for the Plane client or app you created over from your IdP and paste it in the field for it.
40+
41+
The secret is usually auto-generated and you just need to copy it over from the Plane app or client's Home or Settings page.
42+
43+
- Copy the `TOKEN URL` from your IdP and paste it into the field for it on `/god-mode/authentication/oidc/`.\
44+
Typically used to maintain user authentication and to persist it with refreshes, this URL lives in the `.well-known/` directory for the Plane app or client on your IdP.
45+
46+
- Copy the `User info URL` from your IdP and paste it into the field for it on `/god-mode/authentication/oidc/`.
47+
48+
Used to get an authenticating user's `email`, `first_name` and the `last_name` values from the IdP, this too can be copied over from the `.well-known/` directory.
49+
50+
- Copy the `Authorize URL` over from the `.well-known/` directory and paste it into the field for it on Plane's `/god-mode/authentication/oidc/`.\
51+
This is the URL that Plane's login screen redirects to when your users click `Sign up with <name of IDP>` or `Login with <name of IdP>`.
52+
53+
<Frame>![Login with IdP](/images/custom-sso/plane-login.png)</Frame>
54+
55+
To test if this URL is right, see if clicking the `Login with <name of your IdP>` button brings up your IdP's authentication screen.
56+
57+
<Frame>![Login with Okta](/images/custom-sso/okta-signin.webp)</Frame>
58+
59+
- Finally, choose a name for your IdP on Plane so you can recognize this set of configs.
60+
61+
## SAML
62+
63+
You will need to configure values on your IdP first and then on Plane later.
64+
<Tip>
65+
`domain.tld` is the domain that you have hosted your Plane app on.
66+
</Tip>
67+
68+
### On your preferred IdP
69+
70+
Create a Plane client or application per your IdP's documentation and configure ↓.
71+
72+
| **Config** | **Value** |
73+
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
74+
| Entity ID <br/><br/> Metadata that identifies Plane as an authorized service on your IdP | `http(s)://domain.tld/auth/oidc/` |
75+
| ACS URL <br/><br/>Assertion Consumer service that your IdP will redirect to after successful authentication by a user <br/><br/>This is roughly the counterpart of the `Callback URL` in OIDC set-ups. | `http(s)://domain.tld/auth/oidc/callback/` <br/><br/> Plane supports HTTP-POST bindings. |
76+
| SLS URL <br/><br/>Single Logout Service that your IdP will recognize to end a Plane session when a user logs out <br/><br/>This is roughly the counterpart of the `Logout URL` in OIDC set-ups. | `http(s)://domain.tld/auth/oidc/logout/` |
77+
78+
<Tip>
79+
When setting these values up on the IdP, it’s important to remember Plane does not need to provide a signing certificate like other service providers.
80+
</Tip>
81+
82+
### Let your IdP identify your users on Plane.
83+
84+
| **Config** | **Value** |
85+
|----------------------------|--------------------------------------------------------|
86+
| Name ID format | emailAddress <br/><br/> By default, your IdP should send back a username, but Plane recognizes email addresses as the username. Set the value to the above so Plane recognizes the user correctly.
87+
### Set additional attribute values.
88+
89+
By default, your IdP will send the value listed under `Property`. You have to map it to the SAML attribute Plane recognizes.
90+
91+
| **Default property value** | **Plane SAML attribute** |
92+
|----------------------------|--------------------------------------------|
93+
| user.firstName | first_name |
94+
| user.lastName | last_name |
95+
| user.email | email |
96+
97+
<Tip>
98+
Depending on your IdP, you will have to find both the `Name ID format` and the three other user identification properties on different screens. Please refer to your IdP's documentation when configuring these up on your IdP. Additionally, you may have to configure the IdP to sign assertions. Irrespective of that, you have to copy the signing certificate from the IdP.
99+
</Tip>
100+
101+
### On Plane
102+
103+
<Frame>![SAML Configuration](/images/custom-sso/saml-config.png)</Frame>
104+
105+
<Tip>
106+
You will find all of the values for the fields below in the `/metadata` endpoint your IdP generates for the Plane app or client.
107+
</Tip>
108+
109+
- Copy the `ENTITY_ID` for the Plane client or app you just created over from your IdP and paste it in the field for it.
110+
111+
- Copy the `SSO URL` for the Plane client or app from your IdP and paste it in the field for it.
112+
113+
This will bring up the IdP's authentication screen for your users.
114+
115+
<Frame>![SSO URL](/images/custom-sso/okta-signin.webp)</Frame>
116+
117+
- Copy the `SLS URL` for the Plane client or app from your IdP and paste it in the `Logout URL` field on Plane's `/god-mode/authentication/saml/`.
118+
119+
- Add the name of the IdP that you want to show on your Plane instance's log-in or sign-up screens.
120+
121+
<Frame>![Log-in Screen](/images/custom-sso/instance-login.png)</Frame>
122+
123+
- Finally, paste the signing certificate from your IdP that you got in the last step of setting up your Plane client or app on your IdP above and paste it in the field for it.

‎old/plane-one/governance/workspaces-and-teams.mdx

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Workspaces and teams
3+
sidebarTitle: Workspaces and teams
4+
---
5+
6+
Since April 15 when Plane One was announced, we have communicated on our website and Discord that One will have one workspace linked to one domain and one license.
7+
<Tip>By domain, we mean something like `domain.tld` or `subdomain.domain.tld` that you set up to access Plane.</Tip>
8+
This was a carefully deliberate move driven entirely by what Plane stands for and what it should enable from a product point of view.
9+
10+
## Workspaces → Teams
11+
12+
To align the product better with the ethos of collaboration, we will introduce Teams, functional groups within a workspace housing projects mapped to real-world teams or coalitions of members with shared responsibilities for goals and tasks. This change will roll out backwards to the Community Edition + the hosted Cloud and forwards to our self-hosted Enterprise Edition for all our paid plans.
13+
<Tip>Teams will come to One toward the end of June 2024.</Tip>
14+
15+
## Why this change
16+
17+
Plane was conceived, designed, and built for cross-functional collaboration, going beyond just your team or company to include customers. Features like [Intake](https://docs.plane.so/core-concepts/inbox), [Publish](https://docs.plane.so/core-concepts/deploy), and [Pages](https://docs.plane.so/core-concepts/pages/overview) unlock that unique-to-Plane collaboration and will work with other forthcoming paid features. While workspaces have enabled essential separation of team- or org-specific data, we have come to realize they create silos that render our collaboration features moot.
18+
19+
## The short-term plan for One
20+
21+
Because Teams isn’t here and we don’t want to delay getting One into your hands until Teams launches, we will map your Community Edition to One as-is. Meaning, all your workspaces will come to One for a period of three weeks or so. In that time, we will refine and add the finishing touches to Teams. When ready, your One instance will get an update to enable Teams.
22+
23+
## Existing workspaces
24+
25+
You will create a default workspace or choose one from your existing workspaces to be the default, as the case may be. All other workspaces will turn into teams in your default workspace. Projects in other workspaces will become team projects in your default workspace.
26+
27+
## The default workspace
28+
29+
Think of it as your org-wide parent in Plane. It will house teams, members, projects, and organizational settings.
30+
31+
## Other workspaces going forward
32+
33+
While we recommend having just one workspace, there are cases when you need more than one workspace, especially when you are managing data-sensitive clients. We don’t want to put restrictions on the creation of workspaces by instance. Meaning, you can create other workspaces should you need to on the same instance, but only with a new license even if it’s the Free plan or the Community Edition. Each workspace going forward will be linked to a license that becomes the unique identifier between you and us for all workspace management needs.
34+
35+
This unlocks new ways of using workspaces. For example, you could have a One-licensed workspace internally, then a Free workspace for a client, then another Pro-licensed workspace for another client. Billing becomes simpler and more predictable for you.
36+
37+
To answer an obvious question, we can’t turn existing workspaces into the new license-linked workspaces retroactively because of how we were architected in the past. We can only do that going forward.
38+
39+
---
40+
For questions about this, please reach out to us on [Discord](https://discord.com/channels/1031547764020084846/1240291034307497994).

‎old/plane-one/introduction.mdx

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: Meet Plane One
3+
sidebarTitle: Overview
4+
---
5+
6+
[Plane One](https://plane.so/one) is our first licensed self-hosted edition for growing teams serious about staying in control. One unlocks security, governance, and project management features scale-ups need to manage their instance and projects better.
7+
8+
## Good to know
9+
1. Plane One is a self-hosted-only solution. To use our hosted Cloud editions, [go here](https://app.plane.so).
10+
2. Plane One only works with a domain, not with an IP addresses or `localhost`.
11+
3. Plane One comes with updates for two years with an option to auto-update to latest versions when they are released.
12+
4. Plane One works well for up to 100 users. If you have more than 100 users, you should consider [our Pro plan](https://plane.so/pricing).
13+
14+
## Getting your Plane One license
15+
16+
If you have already purchased a Plane One license, go to https://prime.plane.so and log in with the same email address you used at the time of purchase. To figure out that email address, look for an email from `@plane.so` or Stripe with the subject, "**Your Plane One order**".
17+
18+
When you log in, you will see a list of your licenses. Clicking any will show you your license info and the command you should copy to start deploying One.
19+
20+
<Tip>If you are yet to get a license, do that [here](https://plane.so/one).</Tip>
21+
22+
## Quickstart
23+
Plane One installs with a single command on your CLI. [Learn more](/self-hosting/methods/docker-compose).
24+
25+

‎old/plane-one/manage/prime-cli.mdx

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Manage your instance
3+
sidebarTitle: Instance
4+
---
5+
<Warning>Update your CLI with the command `sudo prime-cli update-cli` before you download any Plane One updates. The latest version of the CLI ensures your Plane upgrades happen smoothly.</Warning>
6+
7+
The Prime CLI is our own command-line interface to help you install, upgrade, and manage your instance without being a pro at Docker. -
8+
9+
Bring up the Prime CLI with ```sudo prime-cli``` from any directory on your machine.
10+
11+
- The three operators you will use the most are,
12+
13+
- `start`
14+
15+
You will use this to start a service in the Docker network with the name of the service.
16+
17+
- `stop`
18+
19+
You will use this to stop a service in the Docker network with the name of the service.
20+
21+
- `restart`
22+
23+
You will use this to restart a service in the Docker network with the name of the service as a `{param or flag}`.
24+
- Often, you will want to monitor the health of your instance and see if some services are up or down. Use `monitor` to do that.
25+
26+
- `healthcheck` is another useful utility that lets you see the status and errors, if any, of all running services
27+
28+
- `repair` fixes your Plane install for common errors automatically.
29+
30+
- `update-cli` downloads and installs the latest version of Prime CLI.
31+
<Tip>
32+
It is highly recommend to run this first before you download any Plane One updates. The latest version of the CLI ensures your Plane upgrades happen smoothly.
33+
</Tip>
34+
35+
36+
For more advanced admins that want greater control over their instance, the list of additional commands available on Prime CLI follow.
37+
- `configure`
38+
39+
Brings up a step form to let you specify the following.
40+
<Accordion title="Steps to configure your instance">
41+
- `Listening port`
42+
43+
Specify the port that the built-in reverse proxy will use
44+
45+
Default value: 80
46+
47+
- `Max file-upload size`
48+
49+
Specify a size in MBs for how big each file uploaded to your Plane app can be
50+
51+
Default value: 5 MB
52+
53+
- `External Postgres URL`
54+
55+
Specify the URL of your own hosted Postgres if you would like to change the database your Plane app uses.
56+
57+
Default database: Postgres 15.5 in the Docker container
58+
59+
- `External Redis URL`
60+
61+
Specify the URL of your own hosted REdis if you would like to change the default Redis Plane ships with.
62+
63+
Default Redis: Redis 7.2.4
64+
65+
- `External storage`
66+
67+
Specify your AWS S3 bucket's credentials in the format below to change storage from the default Plane ships with.
68+
- AWS Access Key ID
69+
- AWS Secret Access Key
70+
- AWS S3 Bucket Name
71+
72+
Default storage: MinIO
73+
74+
- Confirm your choices on the screen ↓.
75+
76+
This restarts your instance with the new configs.
77+
</Accordion>
78+
79+
- `upgrade`
80+
81+
checks your instance for available version upgrades and asks you for a confirmation before downloading the latest available version.
82+
1. Typing `YES` lets the CLI automatically download's the latest version and installs it. Then it restarts the instance to load the latest app.
83+
2. Typing `NO` cancels the upgrade.
84+
85+
- `uninstall`
86+
87+
uninstalls Plane. Before it goes through, it asks you for a confirmation.
88+
1. Typing `YES` lets the CLI clean up the `/opt/plane` folder, leaving behind the `/opt/plane/data` and `/opt/plane/logs` folders.
89+
2. Typing `NO` cancels the uninstall.
90+
91+
92+
93+
94+
95+

‎old/plane-one/manage/prime-client.mdx

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Manage your license
3+
sidebarTitle: License
4+
---
5+
6+
After you purchase Plane One, you can log in to our customer portal(https://prime.plane.so) and find your license in the portal.
7+
8+
You can also choose to buy multiple Plane One licenses from here and post your purchase you can see all of them listed here.
9+
10+
## Manage licenses
11+
12+
After you login, you can find all the licenses listed in a single place. All licenses, will show the key and the domain attached to the purchase. This makes it easy to identify which license corresponds to which domain, should you choose to buy multiple licenses.
13+
<Frame>
14+
<img src="/images/plane-one/prime-all-licenses.png"/>
15+
</Frame>
16+
## View license details
17+
18+
Once you select a license from the list, you quickly get information on how to setup plane one via our suggested setup methods. You can also download the invoice for your Plane One purchase here and copy your license key
19+
<Frame>
20+
<img src="/images/plane-one/prime-inside-a-license.png"/>
21+
</Frame>
22+
<Note>We will soon add health metrics of your instance in this page, so that you can also monitor the health of your Plane One instance here.</Note>
23+
24+
## Buy a new plane one license
25+
26+
Within the customer portal, you can buy a new license for Plane One directly and self-host a new instance of Plane One.

‎old/plane-one/self-host/guides.mdx

Whitespace-only changes.

0 commit comments

Comments
 (0)