chore: add dev docs on mintlify (#16935)
* --init * progress... * add more docs * bunch of changes and added back platform * development guides added * more guides in develop with cal * self hosted WIP * deployments * fix deployment steps * self-hosted guides * .. * Removed the development only sections * Removed 'with Cal.com' * use steps component for steps --------- Co-authored-by: Keith Williams <keithwillcode@gmail.com>
This commit is contained in:
Syed Ali Shahbaz
co-authored by
Keith Williams
Keith Williams
parent
66378160df
commit
da55306a5a
@@ -15,6 +15,12 @@ Test mode secret keys have the prefix `cal_` and live mode secret keys have the
|
||||
|
||||
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
|
||||
|
||||
Authentication to the API is performed via the Authentication header like: `Bearer: cal_live_xxxxxx`
|
||||
Authentication to the API is performed via the Authorization header. For example, the request would go something like:
|
||||
|
||||
```
|
||||
'Authorization': 'Bearer YOUR_API_KEY'
|
||||
```
|
||||
|
||||
in your request header.
|
||||
|
||||
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: "How to setup API in a local instance"
|
||||
---
|
||||
|
||||
To test API in your local instance, you have the following pre-requisites:
|
||||
|
||||
<Steps>
|
||||
<Step title="Clone the cal.com repository">
|
||||
Please close the cal.com repository. You can do it by following the instructions provided in [Installation](/developing/local-development)
|
||||
</Step>
|
||||
<Step title="Add license key in .env">
|
||||
Add a staging license key that goes in as value for `CALCOM_LICENSE_KEY` in your root `.env` file.
|
||||
|
||||
You can use the following as staging license key
|
||||
```
|
||||
1a1f8138-0bfc-4f37-b4af-1e24fd145839
|
||||
```
|
||||
</Step>
|
||||
<Step title="Install API submodule">
|
||||
Next, you need to install API submodule by following the instructions provided in [API submodule](/developing/local-development#api)
|
||||
</Step>
|
||||
<Step title="Start development server and create API key">
|
||||
Start the cal.com server using `yarn dev` on localhost and create the test API keys by visiting `/settings/developer/api-keys`
|
||||
</Step>
|
||||
<Step title="Start API server and test API">
|
||||
Start the API server by running `yarn workspace @calcom/api dev` and start testing your API locally
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Info>By default, the app server runs on port 3000 and the API server runs on port 3003</Info>
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "Adding your first app"
|
||||
---
|
||||
|
||||
Head over to the **apps** page, where you'll find our app store. We suggest firstly adding a calendar integration, then optionally a video conferencing platform, and then try out the other apps.
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.youtube.com/watch?v=V6mwvgcAxi0"
|
||||
title="Adding your first app"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
Find the app you'd like to install, and either click **Install** in the top right of that app's card to add it right away, or click on the app's card to view more details.
|
||||
|
||||
In the details page you can read more about each app, then click **Install** in the top right of the page to add it to your account.
|
||||
|
||||
<img src="./images/i1599x929-tUttNKwBum0Z_p1vwkt.png"
|
||||
legend="The app details page for Google calendar"
|
||||
/>
|
||||
|
||||
If the app requires authentication, for instance to connect your Google Account, a dialog will be opened prompting you to authenticate. Once complete, the app will be successfully installed.
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: "Build a greeter app"
|
||||
---
|
||||
|
||||
## Building a **Greeter** app
|
||||
|
||||
<Steps>
|
||||
<Step title="Create an app">
|
||||
Create an app with the title "**Greeter".** Run the following command and provide the information it is looking for.
|
||||
|
||||
```bash
|
||||
yarn app-store create
|
||||
```
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://cdn.iframe.ly/AK13z2x"
|
||||
title="Step 1"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
</Step>
|
||||
<Step title="Install the app">
|
||||
The app is created in Step 1 and we should install it now.
|
||||
</Step>
|
||||
<Step title="Add the functionality">
|
||||
The app is installed but it doesn't do anything because we haven't written added any functionality to it. Let's add a button in the main navigation that greets the user.
|
||||
|
||||
|
||||
1. Create a component `greeter/components/GreeterButton.tsx` - You can name it whatever you want.
|
||||
|
||||
2. Import this component in `Shell.tsx` and add it wherever you want to so that the button is available on all pages.
|
||||
|
||||
```js
|
||||
/**
|
||||
* GreeterButton.tsx
|
||||
* It creates a button that can be added anywhere. The button is visible only if the app is installed.
|
||||
*/
|
||||
import useApp from "@calcom/lib/hooks/useApp";
|
||||
import showToast from "@calcom/lib/notification";
|
||||
import { Button } from "@calcom/ui";
|
||||
|
||||
import useMeQuery from "@lib/hooks/useMeQuery";
|
||||
|
||||
export default function GreeterButton() {
|
||||
const { data: user } = useMeQuery();
|
||||
const { data: greeterApp } = useApp("greeter");
|
||||
// Make sure that greeterApp is installed. We shouldn't show the button when app is not installed
|
||||
if (!user || !greeterApp) {
|
||||
return null;
|
||||
}
|
||||
return (
|
||||
<Button
|
||||
onClick={() => {
|
||||
showToast("Hello, " + user.name, "success");
|
||||
}}
|
||||
>
|
||||
Greet Me!
|
||||
</Button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
```;
|
||||
/**
|
||||
* Shell.tsx
|
||||
*/
|
||||
// ...
|
||||
import GreeterButton from "@calcom/app-store/greeter/components/GreeterButton";
|
||||
// ...
|
||||
|
||||
<GreeterButton />;
|
||||
```
|
||||
|
||||
<img src="./images/i1280x250-dXnl-QuzSMbl_xydd9y.png" />
|
||||
|
||||
|
||||
A sample line where I used the component in the demo
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.loom.com/embed/b0fd31cc11444799af7a6f12a01d4321"
|
||||
title="Step 3"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it. You now have a fully functional Greeter app. This is the simplest possible demonstration of how you can build an app and what it can do. There are simply no restrictions on what an app can achieve.
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: "How to build an app"
|
||||
---
|
||||
|
||||
Since Cal.com is open source we encourage developers to create new apps for others to use. This guide is to help you get started.
|
||||
|
||||
You can create an app by simply running the following command. It creates a new directory under [`packages/app-store/`](https://github.com/calcom/cal.com/tree/main/packages/app-store)``
|
||||
|
||||
```bash
|
||||
yarn create-app
|
||||
```
|
||||
|
||||
|
||||
You just need to provide a few inputs and then you will have your app created within a few seconds. [See, how you can build a very simple app that greets your users.](/developing/guides/appstore-and-integration/build-a-greeter-app)
|
||||
|
||||
### Steps in creating an app
|
||||
|
||||
<Steps>
|
||||
<Step title="Create app">
|
||||
Create the app using the `create-app` command. The app can be installed now, but at this moment it isn't doing anything. It is just installed and ready to do what you want it to do.
|
||||
</Step>
|
||||
<Step title="Adding the functionalities">
|
||||
There is pretty much no restriction on what an App can do. For example:
|
||||
|
||||
- Hooking into existing functionalities to enhance them - _In all these cases you need to first check if the app is installed or not. There is_ `_useApp(appSlug)_` _react hook to do that. It gives you the app details if the app is installed._
|
||||
- Apps that need to connect with third parties like Google Calendar, Apple Calendar, Google Meet.
|
||||
- A very powerful app that has its own data and pages - [Routing Forms App](https://github.com/calcom/cal.com/tree/main/packages/app-store/ee/routing_forms) is a great example of this.
|
||||
- There are other powerful apps already in the [App Store](https://app.cal.com/apps) that you can get an idea of the capabilities of apps.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
|
||||
### Structure
|
||||
|
||||
All apps can be found under [`packages/app-store`](https://github.com/calcom/cal.com/tree/main/packages/app-store). In this folder is `_baseApp` which shows the general structure of an app.
|
||||
|
||||
```bash
|
||||
├──_example
|
||||
| ├──config.json -> Autogenerated by cli. You are free to edit it.
|
||||
| ├──api
|
||||
| | ├──add.ts -> Autogenerated by cli. You would want to edit it if your app needs to connect with a third party
|
||||
|
|
||||
| ├──components
|
||||
|
|
||||
| ├──static -> Add all static assets here
|
||||
| | ├──icon.svg -> This is used as the logo for your App.
|
||||
|
||||
| ├──index.ts
|
||||
| ├──package.json
|
||||
| ├──.env.example -> Specify the environmental variables (ex. auth token, API secrets) that your app will need if it's applicable
|
||||
| ├──README.mdx -> Customize your app description. You can add an image slider as well.
|
||||
```
|
||||
|
||||
### Other Commands
|
||||
|
||||
**Deleting an app:**
|
||||
|
||||
```bash
|
||||
yarn app-store delete --slug APP_NAME
|
||||
```
|
||||
|
||||
**Editing an app:**
|
||||
|
||||
```bash
|
||||
yarn app-store edit --slug APP_NAME
|
||||
```
|
||||
|
||||
### Important Points
|
||||
|
||||
* Make sure to have `yarn app-store:watch` command running when developing an app so that autogenerated files are always up to date.
|
||||
|
||||
* If app-store cli fails at this step, try to run this command manually first. Solve that problem and then re-run cli. The command can fail because there are Prisma migrations that can't be applied automatically.
|
||||
|
||||
<img src="./images/i1600x120-WfEdMhsOOLSg_sitk6a.png" />
|
||||
|
||||
A sample failure in create command
|
||||
|
||||
* When you edit an app following things aren't updated.
|
||||
|
||||
* README.mdx - It would still have the old description. Feel free to edit it manually.
|
||||
|
||||
### Publishing Your App to the Cal.com App Store
|
||||
|
||||
Once your app is working in your environment, you can publish it to Cal.com App Store by opening a PR [here](https://github.com/calcom/cal.com).
|
||||
|
||||
If you need any help feel free to join us on [Discord](https://go.cal.com/discord).
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Assign people to a call from a CRM or database"
|
||||
---
|
||||
|
||||
## Option 1: Based on CRM integration
|
||||
|
||||
If you are working with a CRM such as Salesforce, Hubspot, Close.com or similar, you can use our integrations to connect to your apps.
|
||||
|
||||
We're using the Assignee APIs from each service to understand which person is assigned to an email of a new lead.
|
||||
|
||||
By prefilling your booking link with ?email=name@acme.com our integration will look up who has spoken to name@acme.com before and skip all round-robin logic.
|
||||
|
||||
Here is an example URL: i.cal.com/sales/exploration?email=name@acme.com
|
||||
|
||||
This works with Embeds as well, just add the parameter to your CalLink property.
|
||||
|
||||
## Option 2: Based on Emails
|
||||
|
||||
If you are using a different product that we don't integrate with, or you need something more custom you can also achieve this with our Organization plan.
|
||||
|
||||
We've built our Organization system in a way where every email can be turned into a scheduling link with your company subdomain:
|
||||
|
||||
jane@acme.com → acme.cal.com/jane (or schedule.acme.com/jane)
|
||||
|
||||
This means if you have a table
|
||||
|
||||
| User | AccountExecutive |
|
||||
| :----------- | :----------- |
|
||||
| peer@cal.com | jane@acme.com |
|
||||
|
||||
You could show peer@cal.com an embed inside your application simply by using the value from AccountExecutive to build the link:
|
||||
|
||||
jane@acme.com → acme.cal.com/jane either with a string replace function or a simple regex.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Integration with HubSpot"
|
||||
---
|
||||
|
||||
To use Cal.com with HubSpot, you only need two things:
|
||||
|
||||
<Steps>
|
||||
<Step title="Pre-requisite">
|
||||
You need to have an account on both platforms
|
||||
</Step>
|
||||
<Step title="Install Hubspot App">
|
||||
You'll need to go to the [HubSpot app page](https://app.cal.com/apps/hubspot) and click the "Install" button ⬇
|
||||
|
||||
<img src="./images/i1599x807-x2DRUUT-DkbF_yljih9.png" />
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Choose hubspot account">
|
||||
After clicking the "Install" button, you will need to select the HubSpot account you want to use Cal.com with⬇
|
||||
|
||||
<img src="./images/i1600x1287-XKGU-PMvAkrB_zq004d.png" />
|
||||
</Step>
|
||||
<Step title="Connect app">
|
||||
Then, you will need to give the listed permissions to Cal.com clicking the button "Connect app" in order to manage certain aspects of your account, in order to provide you with the functionality you are looking for. By the way, we are making our app official with HubSpot, so you will not be seeing the warning very soon ⬇
|
||||
|
||||
<img src="./images/i1600x1253-8BQ3KGqrqGTp_xrhqzd.png" />
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
---
|
||||
Done! You will be redirected to Cal.com Installed Apps showing your newly installed app ready for you to take advantage of ⬇
|
||||
|
||||
<img src="./images/i1600x813-fFKsveiL2GuM_wk8cv1.png" />
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: "How to use OAuth to authorize apps"
|
||||
---
|
||||
|
||||
As an example, you can view our OAuth flow in action on Zapier. Try to connect your cal.com account [here](https://zapier.com/apps/calcom/integrations).
|
||||
To enable OAuth in one of your apps, you will need a Client ID, Client Secret, Authorization URL, Access Token Request URL, and Refresh Token Request URL.
|
||||
|
||||
<img src="./images/oauth-zapier.png" />
|
||||
|
||||
### OAuth Client Credentials
|
||||
Only the cal.com team can create new OAuth clients. Please contact us at [support@cal.com](mailto:support@cal.com) with the following details: client name, redirect URI (provided by the app), app logo, and a link to the app.
|
||||
|
||||
The Cal.com team will register the app and provide you with the Client ID and Client Secret. Keep these credentials confidential and secure.
|
||||
|
||||
### Authorization URL
|
||||
To initiate the OAuth flow, direct users to the following authorization URL:
|
||||
- `https://app.cal.com/auth/oauth2/authorize`
|
||||
- URL Parameters:
|
||||
- *client_id*
|
||||
- *state*: A securely generated random string to mitigate CSRF attacks
|
||||
- *redirect_uri*: This is where users will be redirected after authorization
|
||||
- *scope*: Specify the required scopes. Current scopes include READ_BOOKING and READ_PROFILE. Additional scopes can be added as needed.
|
||||
|
||||
After users click *Allow*, they will be redirected to the redirect_uri with the code (authorization code) and state as URL parameters.
|
||||
|
||||
### Access Token Request
|
||||
Endpoint: `POST https://app.cal.com/api/auth/oauth/token`
|
||||
|
||||
Request Body:
|
||||
- *code*: The authorization code received in the redirect URI
|
||||
- *client_id*
|
||||
- *client_secret*
|
||||
- *grant_type*: "authorization_code"
|
||||
- *redirect_uri*
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
access_token: “exampleAccessToken”
|
||||
refresh_token: “exampleRefreshToken”
|
||||
}
|
||||
```
|
||||
|
||||
### Refresh Token Request
|
||||
Endpoint: `POST https://app.cal.com/api/auth/oauth/refreshToken`
|
||||
|
||||
Request Body:
|
||||
- *grant_type*: "refresh_token"
|
||||
- *client_id*
|
||||
- *client_secret*
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
access_token: “exampleAccessToken”
|
||||
}
|
||||
```
|
||||
|
||||
### Testing OAuth Credentials
|
||||
To verify the correct setup and functionality of OAuth credentials you can use the following endpoint:
|
||||
`GET https://app.cal.com/api/auth/oauth/me`
|
||||
|
||||
Headers:
|
||||
- Authorization: Bearer *exampleAccessToken*
|
||||
|
||||
|
||||
### Authorize requests with Bearer token
|
||||
Ensure that Cal.com endpoints accessed by the app support authentication via Bearer Token.
|
||||
If this is not the case, it will be necessary to update the code accordingly.
|
||||
Here is an example of an endpoint that supports both apiKey and Bearer token authentication: [/listBookings endpoint](https://github.com/calcom/cal.com/blob/main/packages/app-store/zapier/api/subscriptions/listBookings.ts)
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "Setting up OIDC with okta"
|
||||
---
|
||||
|
||||
<Steps>
|
||||
<Step title="Create an application with your OIDC provider">
|
||||
For example, in Okta, once you create an account, you can click on Applications on the sidebar menu:
|
||||
<img src="./images/i1600x900-oVjaQ0tU3AnO_wrzp85.png" />
|
||||
</Step>
|
||||
<Step title="Click on Create App Integration">
|
||||
<img src="./images/i1600x900-wrIlZkLdZ6kL_wf7mxn.png" />
|
||||
</Step>
|
||||
<Step title="Select OIDC in the modal form, along with Web App, and click Next">
|
||||
<img src="./images/i1600x900-IfRWYg8XuCMI_tkwyft.png" />
|
||||
</Step>
|
||||
<Step title="Enter the Sign in redirect URL and sign out URL">
|
||||
Enter the Sign in redirect URL (or auth URL) as:
|
||||
```
|
||||
https://app.cal.com/api/auth/oidc
|
||||
```
|
||||
And the sign out URL as:
|
||||
```
|
||||
https://app.cal.com/auth/login
|
||||
```
|
||||
<img src="./images/i1600x900-TqgDJpBoiR-C_onrwit.png" />
|
||||
</Step>
|
||||
<Step title="Gather Client Secret, Client ID, and Well Known URL">
|
||||
Now you should have the Client Secret and Client ID with you. You would also need the Well Known URL which for Okta is generally of the type:
|
||||
```
|
||||
https://{yourOktaDomain}/.well-known/openid-configuration
|
||||
```
|
||||
So, if your Okta domain is `dev-123456.okta.com`, your well known URL would be:
|
||||
```
|
||||
https://dev-123456.okta.com/.well-known/openid-configuration
|
||||
```
|
||||
</Step>
|
||||
<Step title="Log in">
|
||||
Log in with the Organization Admin user.
|
||||
</Step>
|
||||
<Step title="Go to Organization SSO Settings">
|
||||
Visit `https://app.cal.com/settings/organizations/sso` and you should see something like this:
|
||||
<img src="./images/i1600x900-8ufcUyCOVwV6_hdudno.png" />
|
||||
</Step>
|
||||
<Step title="Configure SSO with OIDC">
|
||||
Click on Configure SSO with OIDC, and then enter the Client Secret, Client ID, and Well Known URL from Step 5, and click save.
|
||||
<img src="./images/i1600x900-GN1NLgrcf5r4_tmhni3.png" />
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it. Now when you try to login with SSO, your application on Okta will handle the authentication.
|
||||
@@ -0,0 +1,82 @@
|
||||
<Steps>
|
||||
<Step title="Create an application with your OIDC provider">
|
||||
For example, in Okta, once you create an account, you can click on Applications on the sidebar menu:
|
||||
<img src="./images/i1600x900-oVjaQ0tU3AnO_wrzp85.png" />
|
||||
</Step>
|
||||
<Step title="Click on Create App Integration">
|
||||
<img src="./images/i1600x900-wrIlZkLdZ6kL_wf7mxn.png" />
|
||||
</Step>
|
||||
<Step title="Select SAML or OIDC and Web App, then click Next">
|
||||
Note you will have to fill in the appropriate fields for the SAML or OIDC setup to continue.
|
||||
- [SAML Setup](/developing/guides/auth-and-provision/sso-setup#setting-up-saml-login)
|
||||
- [OIDC Setup](/developing/guides/auth-and-provision/sso-setup#setting-up-oidc-login)
|
||||
<img src="./images/i1600x900-IfRWYg8XuCMI_tkwyft.png" />
|
||||
</Step>
|
||||
<Step title="Enable SCIM provisioning">
|
||||
Once the application is created, under General -> App Settings, click "Edit" and then the checkbox "Enable SCIM provisioning".
|
||||
<img src="./images/scim/app-settings-enable-scim.webp" />
|
||||
</Step>
|
||||
<Step title="Go to Directory Sync in Cal.com">
|
||||
Next, go to your instance of Cal.com and navigate to `https://app.cal.com/settings/organization/dsync` and click configure.
|
||||
<img src="./images/scim/dsync-configure.webp" />
|
||||
</Step>
|
||||
<Step title="Configure Directory Sync">
|
||||
In the "Configure Directory Sync" form, choose a directory sync name and select "Okta SCIM v2.0" as the "Directory Provider".
|
||||
<img src="./images/scim/dsync-configure-provider.webp" />
|
||||
</Step>
|
||||
<Step title="Take note of SCIM Base URL and SCIM Bearer Token">
|
||||
<img src="./images/scim/dsync-configure-info.webp" />
|
||||
</Step>
|
||||
<Step title="Setup Provisioning in Okta">
|
||||
In Okta, go to your application. Navigate to the "Provisioning" tab and click "Integration" under "Settings".
|
||||
<img src="./images/scim/okta-dsync-options.webp" />
|
||||
- Under "SCIM connector base URL" enter the "SCIM Base URL" from Cal.com
|
||||
- Under "Unique identifier field for users" enter "email"
|
||||
- Under "Supported provisioning actions" enable:
|
||||
- "Import New Users and Profile Updates"
|
||||
- "Push New Users"
|
||||
- "Push Profile Updates"
|
||||
- "Push Groups"
|
||||
- Under "Authentication Mode" choose "HTTP Header"
|
||||
- Under "Authentication" enter the "SCIM Bearer Token" from Cal.com
|
||||
- When you hit save, it will make a test call to the "SCIM Base URL"
|
||||
</Step>
|
||||
<Step title="Go to the 'To App' settings">
|
||||
After saving, navigate to the "To App" settings, still under the "Provisioning" tab.
|
||||
</Step>
|
||||
<Step title="Enable Provisioning to App">
|
||||
Under "Provisioning to App", click "Edit" and enable:
|
||||
- "Create User"
|
||||
- "Update User Attributes"
|
||||
- "Deactivate User"
|
||||
</Step>
|
||||
<Step title="Update Attribute Mapping">
|
||||
Under "\{Your application name\} Attribute Mapping," remove all fields except for:
|
||||
- "username"
|
||||
- "givenName"
|
||||
- "familyName"
|
||||
- "email"
|
||||
- "displayName"
|
||||
</Step>
|
||||
<Step title="Map Attributes from Okta Profile">
|
||||
Set each of these properties to "Map from Okta Profile" and the related field. Under "Apply On" select "Create and Update".
|
||||
<img src="./images/scim/okta-property-settings.webp" />
|
||||
</Step>
|
||||
<Step title="Assign users and groups to the app">
|
||||
You can now assign users and groups to the app.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Mapping Okta Groups to Cal.com Teams
|
||||
|
||||
When provisioning groups to your organization, Okta groups can be mapped to teams within your organization, and users will be auto-assigned to these teams.
|
||||
|
||||
On `https://app.cal.com/settings/organization/dsync`, there is a table with the teams under your organization. Click on "Add group name" to map the Okta group to the team.
|
||||
|
||||
<Note>
|
||||
The group name must be spelled exactly as it is shown on Okta.
|
||||
</Note>
|
||||
|
||||
When you push the group to your organization, those users will automatically be added to the team.
|
||||
|
||||
<img src="./images/scim/group-team-mapping.webp" />
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: "SSO setup"
|
||||
---
|
||||
|
||||
Cal.com supports both Security Assertion Markup Language (SAML) and OpenID Connect (OIDC), two of the industry's leading authentication protocols. We prioritize your ease of access and security by providing robust Single Sign-On (SSO) capabilities. Whether you're looking for the XML-based standard of SAML or the lightweight OIDC, our platform is equipped to integrate smoothly with your preferred identity provider, ensuring both convenience and security for your users.
|
||||
|
||||
### Setting up SAML login
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a SAML application with your Identity Provider (IdP)">
|
||||
Follow the instructions here - [SAML Setup](/developing/guides/auth-and-provision/sso-setup#saml-registration-with-identity-providers)
|
||||
</Step>
|
||||
<Step title="Configure access to the IdP SAML app">
|
||||
Ensure that all users who need access to Cal.com have access to the IdP SAML app.
|
||||
</Step>
|
||||
<Step title="Retrieve XML metadata from your IdP">
|
||||
Keep the XML metadata from your IdP accessible, as you will need it later.
|
||||
</Step>
|
||||
<Step title="Log in to your Organization Admin account">
|
||||
Visit `settings/organizations/sso`.
|
||||
</Step>
|
||||
<Step title="Configure SSO with SAML">
|
||||
Click on the `Configure` button for `SSO with SAML`.
|
||||
</Step>
|
||||
<Step title="Paste the XML metadata and Save">
|
||||
In the SAML configuration section, copy and paste the XML metadata from step 3 and click on Save.
|
||||
</Step>
|
||||
<Step title="Your users can now log into Cal using SAML">
|
||||
Once setup is complete, provisioned users can log into Cal.com using SAML.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### SAML Registration with Identity Providers
|
||||
|
||||
This guide explains the settings you need to use to configure SAML with your Identity Provider. Once configured, obtain an XML metadata file and upload it on your Cal.com instance.
|
||||
|
||||
> **Note:** Please do not add a trailing slash at the end of the URLs. Create them exactly as shown below.
|
||||
|
||||
**Assertion consumer service URL / Single Sign-On URL / Destination URL:** https://app.cal.com/api/auth/saml/callback
|
||||
|
||||
**Entity ID / Identifier / Audience URI / Audience Restriction:** [https://saml.cal.com](https://saml.cal.com)
|
||||
|
||||
**Response:** Signed
|
||||
|
||||
**Assertion Signature:** Signed
|
||||
|
||||
**Signature Algorithm:** RSA-SHA256
|
||||
|
||||
**Assertion Encryption:** Unencrypted
|
||||
|
||||
**Mapping Attributes / Attribute Statements:**
|
||||
|
||||
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier -> id
|
||||
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress -> email
|
||||
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname -> firstName
|
||||
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname -> lastName
|
||||
|
||||
### Setting up OIDC login
|
||||
|
||||
<Steps>
|
||||
<Step title="Gather necessary credentials">
|
||||
Keep handy the Client Secret, Client ID, and Well Known URL for the next steps.
|
||||
</Step>
|
||||
<Step title="Log in and go to Organization SSO Settings">
|
||||
Visit `/settings/organizations/sso` and you should see something like this:
|
||||
<img src="./images/i1600x900-8ufcUyCOVwV6_hdudno.png" />
|
||||
</Step>
|
||||
<Step title="Configure SSO with OIDC">
|
||||
Click on Configure SSO with OIDC, enter the Client Secret, Client ID, and Well Known URL from Step 1, and click save.
|
||||
<img src="./images/i1600x900-GN1NLgrcf5r4_tmhni3.png" />
|
||||
</Step>
|
||||
<Step title="Complete OIDC setup">
|
||||
Now, when you try to login with SSO, your OIDC provider will handle the authentication.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: "Setting up mailtrap for email testing"
|
||||
---
|
||||
Mailtrap is a versatile tool for testing email notifications without sending them to the real users of your application. It's especially useful for testing and ensuring that the system sends out accurate emails in a secure and efficient manner.
|
||||
|
||||
To set up Mailtrap for email testing on Cal.com, follow these steps:
|
||||
|
||||
<Steps>
|
||||
<Step title="Create an Account">
|
||||
The first step is to register an account with Mailtrap. It offers a free plan for small testing needs, and also paid plans for larger organizations.
|
||||
</Step>
|
||||
<Step title="Create an Inbox">
|
||||
After registering, create an inbox for your application. Each inbox comes with its SMTP and POP3 credentials, which can be used to send and retrieve emails.
|
||||
</Step>
|
||||
<Step title="Configure the Cal.com env file">
|
||||
Change the tab to nodemailer and copy the information to `.env`:
|
||||
```
|
||||
EMAIL_SERVER_HOST='sandbox.smtp.mailtrap.io'
|
||||
EMAIL_SERVER_PORT=2525
|
||||
EMAIL_SERVER_USER='XXX'
|
||||
EMAIL_SERVER_PASSWORD='XXX'
|
||||
```
|
||||
<Info>Please remember to change the user and password and replace 'XXX' above with their respective values.</Info>
|
||||
</Step>
|
||||
<Step title="Set EMAIL_FROM">
|
||||
Set the `EMAIL_FROM` environment variable in the `.env` file. For example:
|
||||
```
|
||||
EMAIL_FROM='notifications@yourselfhostedcal.com'
|
||||
```
|
||||
</Step>
|
||||
<Step title="Send Test Emails">
|
||||
Once your instance is configured, you can start sending test emails. These emails are "trapped" in the Mailtrap inbox, enabling you to verify email content, headers, and attachments.
|
||||
</Step>
|
||||
<Step title="Analyze and Debug">
|
||||
Mailtrap provides features to analyze and debug your emails. You can check whether the HTML displays correctly, ensure the email is not treated as spam, and also see if it contains any broken links, invalid format, or incorrect images.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Happy testing!
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Embed Events
|
||||
---
|
||||
|
||||
## Actions
|
||||
|
||||
You can listen to an action that occurs in embedded cal link as follows. You can think of them as DOM events. We are avoiding the term "events" to not confuse it with Cal Events.
|
||||
|
||||
```js
|
||||
<script>
|
||||
Cal("on", {
|
||||
action: "ANY_ACTION_NAME",
|
||||
callback: (e)=>{
|
||||
// `data` is properties for the event.
|
||||
// `type` is the name of the action(You can also call it type of the action.) This would be same as "ANY_ACTION_NAME" except when ANY_ACTION_NAME="*" which listens to all the events.
|
||||
// `namespace` tells you the Cal namespace for which the event is fired/
|
||||
const {data, type, namespace} = e.detail;
|
||||
}
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
## Following are the list of supported actions.
|
||||
|
||||
| Action | Description | Properties |
|
||||
|----------------------|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
|
||||
| eventTypeSelected | When user chooses an event-type from the listing. | `eventType: object` // Event Type that has been selected |
|
||||
| bookingSuccessful | When the booking is successfully done. It might not be confirmed. | `confirmed: boolean` // Whether confirmation from organizer is pending or not <br /> `eventType: object` // Event Type that has been booked <br /> `date: string` // Date of Event <br /> `duration: number` // Duration of booked Event <br /> `organizer: object` // Organizer details like name, timezone, email |
|
||||
| linkReady | Tells that the link is ready to be shown now. | None |
|
||||
| linkFailed | Fired if link fails to load. | `code: number` // Error Code <br /> `msg: string` // Human Readable message <br /> `data: object` // More details to debug the error |
|
||||
| __iframeReady | It is fired when the embedded iframe is ready to communicate with parent snippet. This is mostly for internal use by Embed Snippet. | None |
|
||||
| __windowLoadComplete | Tells that window load for iframe is complete. | None |
|
||||
| __dimensionChanged | Tells that dimensions of the content inside the iframe changed. | `iframeWidth: number` <br /> `iframeHeight: number` |
|
||||
|
||||
|
||||
<Info>Actions that start with __ are internal.</Info>
|
||||
|
||||
To get more details on how Embed actually works, you can refer to this [Embed Flowchart](https://www.figma.com/file/zZ5oaUpg12Fuu5mGZrPlP5/Embed-Flowchart).
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: "Introduction"
|
||||
icon: "presentation-screen"
|
||||
---
|
||||
|
||||
<img src="./images/i1440x910-pNoAmSPnktzZ_ecaypm.png" />
|
||||
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card href="/developing/local-development" title="Start developing" icon="rocket">
|
||||
Follow our quickstart guide to start developing with Cal.com
|
||||
</Card>
|
||||
<Card href="/self-hosting" title="Self Host" icon="server">
|
||||
Learn how to self-host Cal.com for controlled instance
|
||||
</Card>
|
||||
<Card href="/api-reference/v2" title="API" icon="code">
|
||||
Learn how to use Cal.com's API to CRUD various Cal resources programmatically
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
|
||||
## Welcome to the Cal.com Documentation!
|
||||
|
||||
This is the documentation for Cal.com, an open source scheduling platform that enables you to take bookings on your own terms. Set your availability, connect your favourite calendar and video conferencing platforms, and share your link. It's that simple.
|
||||
|
||||
It covers everything from setup to usage and development. Here you can explore advice and explanations for all of our features, as well as discover new tips and tricks to get the most out of the Cal.com software. This also includes the more advanced documentation covering how to build on top of Cal.com both in the codebase, by API and more. These guides will go into depth on how you can best integrate and extend Cal.com for your needs.
|
||||
@@ -0,0 +1,179 @@
|
||||
---
|
||||
title: "Local Development"
|
||||
icon: "terminal"
|
||||
---
|
||||
|
||||
Cal.com runs with pretty minimal hardware requirements by itself. The most intensive part for the software is when you actually build the software, but once it's running it's relatively lightweight.
|
||||
|
||||
Cal.com works with a very large range of operating systems, as it only requires JavaScript execution to run. **Cal.com is known to work well with Windows, Mac, Linux and BSD.** Although they do work well on all of them, for production deployments we would suggest Linux as the ideal platform. Any operating system that runs Node.js should be able to work too, but these are some of the common operating systems that we know work well.
|
||||
|
||||
To run Cal.com, you need to install a few things. **Node.js, yarn, Git and PostgreSQL**. We use **Prisma** for database maintenance, and is one of the dependencies. We won’t publish installation guides for these as they have their own resources available on the internet. If you're on Linux/BSD, all of these things should be readily available on your package manager. Your best bet is searching for something like **Debian 12 PostgreSQL**, which will give you a guide to installing and configuring PostgreSQL on Debian Linux 12.
|
||||
|
||||
<Info>
|
||||
To ensure optimal performance and compatibility, we highly recommend using Node.js version 18 for your development environment. This version provides the best balance of stability, features, and security for this project. Please make sure to update your Node.js installation if necessary.
|
||||
</Info>
|
||||
|
||||
## Development Setup & Production Build
|
||||
|
||||
1. **First, you git clone the repository** with the following command, so you have a copy of the code.
|
||||
```git
|
||||
git clone https://github.com/calcom/cal.com.git
|
||||
```
|
||||
|
||||
<Warning>
|
||||
If you are on windows, you would need to use the following command when cloning, with **admin privileges**:
|
||||
```git
|
||||
git clone -c core.symlinks=true https://github.com/calcom/cal.com.git
|
||||
```
|
||||
</Warning>
|
||||
|
||||
2. Then, go into the directory you just cloned with
|
||||
```bash
|
||||
cd cal.com
|
||||
```
|
||||
and run
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
to install all of the dependencies. Essentially, dependencies are just things that Cal.com needs to install to be able to work.
|
||||
|
||||
3. Then, you just need to set up a couple of things. For that, we use a `.env` file. We just need to copy and paste the `.env.example` file and rename the copy to `.env`. Here you'll have a template with comments showing you the settings you need/might want to set.
|
||||
|
||||
4. Next, use the command
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
(or another secret generator tool if you prefer) to generate a key and add it under `NEXTAUTH_SECRET` in the .env file.
|
||||
|
||||
5. You'll also want to fill out the `.env.appStore` file similar to the `.env` file as this includes keys to enable apps.
|
||||
|
||||
**Development tips**
|
||||
|
||||
> Add `NEXT_PUBLIC_DEBUG=1` anywhere in your `.env` to get logging information for all the queries and mutations driven by **trpc**.
|
||||
|
||||
```bash
|
||||
echo 'NEXT_PUBLIC_DEBUG=1' >> .env
|
||||
```
|
||||
|
||||
> For email testing, set it to "1" if you need to email checks in E2E tests locally. Make sure to run mailhog container manually or with `yarn dx`.
|
||||
|
||||
```bash
|
||||
echo 'E2E_TEST_MAILHOG_ENABLED=1' >> .env
|
||||
```
|
||||
|
||||
### E2E Testing
|
||||
|
||||
Be sure to set the environment variable `NEXTAUTH_URL` to the correct value. If you are running locally, as the documentation within `.env.example` mentions, the value should be `http://localhost:3000`.
|
||||
|
||||
|
||||
In a terminal just run:
|
||||
```bash
|
||||
yarn test-e2e
|
||||
```
|
||||
To open last HTML report run:
|
||||
```bash
|
||||
yarn playwright show-report test-results/reports/playwright-html-report
|
||||
```
|
||||
|
||||
### Manual setup
|
||||
|
||||
1. Configure environment variables in the .env file. Replace `<user>`, `<pass>`, `<db-host>`, `<db-port>` with their applicable values
|
||||
|
||||
```bash
|
||||
DATABASE_URL='postgresql://<user>:<pass>@<db-host>:<db-port>'
|
||||
```
|
||||
|
||||
2. Set a 24 character random string in your .env file for the `CALENDSO_ENCRYPTION_KEY` (You can use a command like
|
||||
```bash
|
||||
openssl rand -base64 24
|
||||
```
|
||||
to generate one).
|
||||
|
||||
3. Set up the database using the Prisma schema (found in `apps/web/prisma/schema.prisma`)
|
||||
|
||||
```bash
|
||||
yarn workspace @calcom/prisma db-deploy
|
||||
```
|
||||
|
||||
4. Run (in development mode)
|
||||
|
||||
```bash
|
||||
yarn dev
|
||||
```
|
||||
|
||||
<Info>
|
||||
When you're testing out the enterprise features locally, you should see a warning shown in the image below, clarifying the need to purchase a license for such features in production.
|
||||
<img src="./images/i1600x900-E4RcIPb1_bYp_hcpsya.png" />
|
||||
</Info>
|
||||
|
||||
|
||||
## **Development quick start with** **`yarn dx`**
|
||||
|
||||
> * **Requires Docker and Docker Compose to be installed**
|
||||
>
|
||||
>
|
||||
> * Will start a local Postgres instance with a few test users - the credentials will be logged in the console
|
||||
>
|
||||
|
||||
```bash
|
||||
yarn dx
|
||||
```
|
||||
|
||||
## **Cron Jobs**
|
||||
|
||||
There are a few features which require cron job setup. At cal.com, the cron jobs are found in the following directory:
|
||||
```bash
|
||||
/apps/web/pages/api/cron
|
||||
```
|
||||
|
||||
|
||||
## App store seeder
|
||||
|
||||
<Info>
|
||||
We recommend using the admin UI/wizard instead of the seeder to enable app store apps
|
||||
</Info>
|
||||
|
||||
|
||||
## API
|
||||
|
||||
#### Step 1
|
||||
|
||||
Copy the .env files from their respective example files depending on the version of the API (v1 or v2):
|
||||
|
||||
```bash
|
||||
cp apps/api/.env.example apps/api/{version}/.env
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
#### Step 2
|
||||
|
||||
Install packages with yarn:
|
||||
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
|
||||
### Running API server
|
||||
|
||||
Run the API V1 with yarn:
|
||||
|
||||
```bash
|
||||
yarn workspace @calcom/api dev
|
||||
```
|
||||
|
||||
Run the API V2 with yarn:
|
||||
<Info>Please note API V2 requires the database running in docker</Info>
|
||||
|
||||
```bash
|
||||
yarn workspace @calcom/api-v2 dev
|
||||
```
|
||||
|
||||
<Note>
|
||||
On windows, you would need to update the script to explicitly set port to 3003 and run yarn dev under `apps/api/package.json` So, it should look something like this after the changes:
|
||||
|
||||
`"dev": "set PORT=3003 && next dev"` Now, running `yarn workspace @calcom/api dev` should start the server.
|
||||
</Note>
|
||||
|
||||
Open [http://localhost:3003](http://localhost:3003/) with your browser to see the result.
|
||||
|
||||
If you wish to test how API works locally, please [check out our guide here](/developing/guides/api/how-to-setup-api-in-a-local-instance).
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: "Code styling"
|
||||
icon: "pen-fancy"
|
||||
---
|
||||
|
||||
Keeping our code styles consistent is key to making the repository easy to read and work with.
|
||||
|
||||
We use a number of style guides written by other amazing companies, simply because they are widely used and because we like working with them.
|
||||
|
||||
We don't expect you to study every single rule of each style guide, but these are great reference points as to how your code should be styled. We may reject a pull request if your code style significantly differs from these style guides however.
|
||||
|
||||
### ESLint & Prettier
|
||||
Calendso uses the ESLint and Prettier formatting tools, and the repository comes with defined rules for each tool. We recommend setting up both tools and using these to help automatically style your code to our guidelines.
|
||||
|
||||
### JavaScript/TypeScript
|
||||
We use the
|
||||
for all JavaScript and Typescript code.
|
||||
|
||||
### HTML & CSS
|
||||
We use the [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) for any HTML and CSS markup. However, exceptions to the HTML guide apply where JSX differentiates from standard HTML.
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: "Contributor's Guide"
|
||||
icon: "book-open"
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Cal.com is structured as a monorepo using [Turborepo](https://github.com/vercel/turbo). Cal.com is built on [NextJS]("https://github.com/vercel/next.js") with [Typescript]("https://www.typescriptlang.org/"), [PostgreSQL]("https://www.postgresql.org/") database and the interactions with the database are carried out using [Prisma]("https://www.prisma.io/"). We use [TRPC]("https://trpc.io/") for end-to-end typesafe procedure calls to Prisma and utilize [Zod]("https://zod.dev/") for validation and type-safe parsing of API calls.
|
||||
|
||||
## Setting Up the Development Environment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Here is what you need to be able to run Cal.com.
|
||||
- Node.js (Version: >=18.x)
|
||||
- PostgreSQL
|
||||
- Yarn (recommended)
|
||||
|
||||
Cal.com can be set up and run on your machine locally. Please take a look at [this quick guide](https://cal.com/documentation/getting-started/local-development) for instructions on setting it up.
|
||||
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
title="Run cal.com locally"
|
||||
src="https://www.loom.com/embed/2f9d16b0959c4f1eaa5b306300ea4deb"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
|
||||
## Understanding the Project Structure
|
||||
|
||||
Cal.com makes use of Turborepo for a monorepo structure. This allows us to manage multiple code projects (like libraries, apps, services) and share code and resources effectively.
|
||||
|
||||
You can look at [turbo.json](https://github.com/calcom/cal.com/blob/main/turbo.json) to see how we use it. In simple terms,
|
||||
- Each entry in the `pipeline` section corresponds to a different part of the project. Understanding these will help in navigating the codebase.
|
||||
- Knowing which tasks depend on others is crucial for understanding the build process.
|
||||
- The `env` entries under each task highlight the need for specific configuration settings, which you will need to set up in your development environment.
|
||||
- You should focus on the tasks related to the area you are contributing to. For example, if working on the Prisma schema, look at tasks prefixed with `@calcom/prisma`
|
||||
- The various packages can be found in the [/packages](https://github.com/calcom/cal.com/tree/main/packages) folder from the root.
|
||||
- The various pages and components for the web can be found in the [/apps/web](https://github.com/calcom/cal.com/tree/main/apps/web) folder from the root.
|
||||
- The public API related codebase can be found in the [/apps/api](https://github.com/calcom/cal.com/tree/main/apps/api) folder from the root.
|
||||
- The Cal.ai related codebase can be found in the [/apps/ai](https://github.com/calcom/cal.com/tree/main/apps/ai) folder from the root
|
||||
|
||||
## How we use TRPC at cal.com
|
||||
|
||||
Cal.com makes use of the TRPC calls for CRUD operations on the database by utilizing the [useQuery()](https://trpc.io/docs/client/react/useQuery) & [useMutation()](https://trpc.io/docs/client/react/useMutation) hooks. These are essentially wrappers around @tanstack/react-query and you can learn more about them here, respectively: [queries](https://tanstack.com/query/v4/docs/react/guides/queries), [mutations](https://tanstack.com/query/v4/docs/react/guides/mutations).
|
||||
|
||||
Here’s an example usage of useQuery at cal.com:
|
||||
```JS
|
||||
const { data: webhooks } = trpc.viewer.webhook.list.useQuery(undefined, {
|
||||
suspense: true,
|
||||
enabled: session.status === "authenticated",
|
||||
});
|
||||
```
|
||||
|
||||
Here’s an example usage of useMutation at cal.com:
|
||||
```JS
|
||||
const createWebhookMutation = trpc.viewer.webhook.create.useMutation({
|
||||
async onSuccess() {
|
||||
showToast(t("webhook_created_successfully"), "success");
|
||||
await utils.viewer.webhook.list.invalidate();
|
||||
router.back();
|
||||
},
|
||||
onError(error) {
|
||||
showToast(`${error.message}`, "error");
|
||||
},
|
||||
});
|
||||
```
|
||||
Both the examples are taken from [packages/features/webhooks/pages/webhook-new-view.tsx](https://github.com/calcom/cal.com/blob/main/packages/features/webhooks/pages/webhook-new-view.tsx) file. We use the useQuery hook for fetching data from the database. On the contrary, the useMutation hook is used for Creating/Updating/Deleting data from the database.
|
||||
|
||||
The path prior to the useQuery or useMutation hook represents the actual path of the procedure: in this case, [packages/trpc/server/routers/viewer/webhook](https://github.com/calcom/cal.com/tree/main/packages/trpc/server/routers/viewer/webhook). You will find `create.handler.ts` in case of
|
||||
```js
|
||||
trpc.viewer.webhook.create.useMutation()
|
||||
```
|
||||
& `list.handler.ts` in case of
|
||||
```js
|
||||
trpc.viewer.webhook.list.useQuery()
|
||||
```
|
||||
in the path mentioned above. There is usually a schema file in the same directory for each handler as well (_name_.schema.ts). This is generally how we make use of the TRPC calls in the cal.com repo.
|
||||
|
||||
## The Cal.com API V1
|
||||
|
||||
Our [API V1](https://github.com/calcom/cal.com/tree/main/apps/api) uses [zod validations](https://zod.dev/) to keep us typesafe and give us extensive parsing control and error handling. These validations reside in [/apps/api/lib/validations](https://github.com/calcom/cal.com/tree/main/apps/api/lib/validations). We also have [helper](https://github.com/calcom/cal.com/tree/main/apps/api/lib/helpers) and [utility](https://github.com/calcom/cal.com/tree/main/apps/api/lib/utils) functions which are used primarily within our API endpoints.
|
||||
Here’s an example usage of our [zod validation in action with the respective API endpoint](https://github.com/calcom/cal.com/blob/main/apps/api/lib/validations/destination-calendar.ts):
|
||||
```js
|
||||
export const schemaDestinationCalendarBaseBodyParams = DestinationCalendar.pick({
|
||||
integration: true,
|
||||
externalId: true,
|
||||
eventTypeId: true,
|
||||
bookingId: true,
|
||||
userId: true,
|
||||
}).partial();
|
||||
|
||||
const schemaDestinationCalendarCreateParams = z
|
||||
.object({
|
||||
integration: z.string(),
|
||||
externalId: z.string(),
|
||||
eventTypeId: z.number().optional(),
|
||||
bookingId: z.number().optional(),
|
||||
userId: z.number().optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
|
||||
export const schemaDestinationCalendarCreateBodyParams = schemaDestinationCalendarBaseBodyParams.merge(
|
||||
schemaDestinationCalendarCreateParams
|
||||
);
|
||||
```
|
||||
|
||||
And here’s the usage of this validation for parsing the request at the [respective endpoint](https://github.com/calcom/cal.com/blob/main/apps/api/pages/api/destination-calendars/_post.ts):
|
||||
```js
|
||||
async function postHandler(req: NextApiRequest) {
|
||||
const { userId, isAdmin, prisma, body } = req;
|
||||
const parsedBody = schemaDestinationCalendarCreateBodyParams.parse(body);
|
||||
```
|
||||
This is the general approach of validation and parsing in our API submodule.
|
||||
|
||||
## Building Apps for Cal.com
|
||||
|
||||
We’ve got an app store containing apps which complement the scheduling platform. From video conferencing apps such as Zoom, Google Meet, etc. to Calendar Apps such as Google Calendar, Apple Calendar, CalDAV, etc. and even payment, automation, analytics and other miscellaneous apps, it is an amazing space to improve the scheduling experience.
|
||||
|
||||
We have a CLI script in place that makes building apps a breeze. [You can learn more about it here](https://cal.com/docs/how-to-guides/how-to-build-an-app).
|
||||
|
||||
## Running Tests
|
||||
|
||||
### E2E-Testing
|
||||
|
||||
Be sure to set the environment variable `NEXTAUTH_URL` to the correct value. If you are running locally, as the documentation within `.env.example` mentions, the value should be `http://localhost:3000`.
|
||||
|
||||
In a terminal just run:
|
||||
```bash
|
||||
yarn test-e2e
|
||||
```
|
||||
|
||||
To open the last HTML report run:
|
||||
|
||||
```bash
|
||||
`yarn playwright show-report test-results/reports/playwright-html-report`
|
||||
```
|
||||
|
||||
#### Resolving issues
|
||||
|
||||
**E2E test browsers not installed**
|
||||
|
||||
If you face the following error when running `yarn test-e2e`:
|
||||
|
||||
<Warning>
|
||||
Executable doesn't exist at /Users/alice/Library/Caches/ms-playwright/chromium-1048/chrome-mac/Chromium.app
|
||||
</Warning>
|
||||
|
||||
You can resolve it by running:
|
||||
|
||||
```bash
|
||||
npx playwright install
|
||||
```
|
||||
to download test browsers.
|
||||
|
||||
## Contribution and Collaboration Guides
|
||||
|
||||
- [Code Styling Guide](/developing/open-source-contribution/code-styling)
|
||||
- [Pull Requests Guide](/developing/open-source-contribution/pull-requests)
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: "Introduction"
|
||||
icon: "github"
|
||||
---
|
||||
|
||||
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
|
||||
|
||||
- Before jumping into a PR be sure to search [existing PRs](https://github.com/calcom/cal.com/pulls) or [issues](https://github.com/calcom/cal.com/issues) for an open or closed item that relates to your submission.
|
||||
|
||||
### Priorities
|
||||
|
||||
| Type of issue | Priority |
|
||||
| :-------------------------------------------------------------- | :-------------------------------------------------- |
|
||||
| Minor improvements, non-core feature requests | <img className="m-0" noZoom src="./images/low-priority.svg" /> |
|
||||
| Confusing UX (... but working) | <img className="m-0" noZoom src="./images/medium-priority.svg" /> |
|
||||
| Core Features (Booking page, availabilty, timezone calculation) | <img className="m-0" noZoom src="./images/high-priority.svg" /> |
|
||||
| Core Bugs (Login, Booking page, Emails are not working) | <img className="m-0" noZoom src="./images/urgent-priority.svg" /> |
|
||||
|
||||
|
||||
### Developing
|
||||
|
||||
The development branch is `main`. This is the branch that all pull
|
||||
requests should be made against. The changes on the `main`
|
||||
branch are tagged into a release monthly.
|
||||
|
||||
To develop locally:
|
||||
|
||||
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your
|
||||
own GitHub account and then
|
||||
[clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
|
||||
2. Create a new branch:
|
||||
|
||||
```bash
|
||||
git checkout -b MY_BRANCH_NAME
|
||||
```
|
||||
|
||||
3. Install yarn:
|
||||
|
||||
```bash
|
||||
npm install -g yarn
|
||||
```
|
||||
|
||||
4. Install the dependencies with:
|
||||
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
|
||||
5. Start developing and watch for code changes:
|
||||
|
||||
```bash
|
||||
yarn dev
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
You can build the project with:
|
||||
|
||||
```bash
|
||||
yarn build
|
||||
```
|
||||
|
||||
Please be sure that you can make a full production build before pushing code.
|
||||
|
||||
### Testing
|
||||
|
||||
More info on how to add new tests coming soon.
|
||||
|
||||
### Running tests
|
||||
|
||||
This will run and test all flows in multiple Chromium windows to verify that no critical flow breaks:
|
||||
|
||||
```bash
|
||||
yarn test-e2e
|
||||
```
|
||||
|
||||
### Linting
|
||||
|
||||
To check the formatting of your code:
|
||||
|
||||
```bash
|
||||
yarn lint
|
||||
```
|
||||
|
||||
If you get errors, be sure to fix them before committing.
|
||||
|
||||
### Making a Pull Request
|
||||
|
||||
- Be sure to [check the "Allow edits from maintainers" option](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) while creating you PR.
|
||||
- If your PR refers to or fixes an issue, be sure to add `refs #XXX` or `fixes #XXX` to the PR description. Replacing `XXX` with the respective issue number. See more about [Linking a pull request to an issue
|
||||
](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
|
||||
- Be sure to fill the PR Template accordingly.
|
||||
|
||||
### Guidelines for committing yarn lockfile
|
||||
|
||||
Do not commit your `yarn.lock` unless you've made changes to the `package.json`. If you've already committed `yarn.lock` unintentionally, follow these steps to undo:
|
||||
|
||||
If your last commit has the `yarn.lock` file alongside other files and you only wish to uncommit the `yarn.lock`:
|
||||
```git
|
||||
git checkout HEAD~1 yarn.lock
|
||||
git commit -m "Revert yarn.lock changes"
|
||||
```
|
||||
If you've pushed the commit with the `yarn.lock`:
|
||||
1. Correct the commit locally using the above method.
|
||||
2. Carefully force push:
|
||||
|
||||
```git
|
||||
git push origin <your-branch-name> --force
|
||||
```
|
||||
|
||||
If `yarn.lock` was committed a while ago and there have been several commits since, you can use the following steps to revert just the `yarn.lock` changes without impacting the subsequent changes:
|
||||
|
||||
1. **Checkout a Previous Version**:
|
||||
- Find the commit hash before the `yarn.lock` was unintentionally committed. You can do this by viewing the Git log:
|
||||
```git
|
||||
git log yarn.lock
|
||||
```
|
||||
- Once you have identified the commit hash, use it to checkout the previous version of `yarn.lock`:
|
||||
```git
|
||||
git checkout <commit_hash> yarn.lock
|
||||
```
|
||||
|
||||
2. **Commit the Reverted Version**:
|
||||
- After checking out the previous version of the `yarn.lock`, commit this change:
|
||||
```git
|
||||
git commit -m "Revert yarn.lock to its state before unintended changes"
|
||||
```
|
||||
|
||||
3. **Proceed with Caution**:
|
||||
- If you need to push this change, first pull the latest changes from your remote branch to ensure you're not overwriting other recent changes:
|
||||
```git
|
||||
git pull origin <your-branch-name>
|
||||
```
|
||||
- Then push the updated branch:
|
||||
```git
|
||||
git push origin <your-branch-name>
|
||||
```
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: "Pull requests"
|
||||
icon: "code-pull-request"
|
||||
---
|
||||
|
||||
### Requirements
|
||||
|
||||
We have a number of requirements for PRs to ensure they are as easy to review as possible and to ensure that they are up to standard with the code.
|
||||
|
||||
### Title & Content
|
||||
|
||||
|
||||
Start by providing a short and concise title. Don’t put something generic (e.g. bug fixes), and instead mention more specifically what your PR achieves, for instance “Fixes dropdown not expanding on settings page”.
|
||||
|
||||
For the PR description, you should go into much greater detail about what your PR adds or fixes. Firstly, the description should include a link to any relevant issues or discussions surrounding the feature or bug that your PR addresses.
|
||||
|
||||
### Feature PRs
|
||||
|
||||
Give a functional overview of how your feature works, including how the user can use the feature. Then, share any technical details in an overview of how the PR works (e.g. “Once the user enters their password, the password is hashed using BCrypt and stored in the Users database field”).
|
||||
|
||||
### Bug Fix PRs
|
||||
|
||||
Give an overview of how your PR fixes the bug both as a high-level overview and a technical explanation of what caused the issue and how your PR resolves this.
|
||||
|
||||
Feel free to add a short video or screenshots of what your PR achieves. Loom is a great way of sharing short videos.
|
||||
|
||||
### Code Quality & Styling
|
||||
|
||||
All submitted code must match our [code styling](/code-styling) standards. We will reject pull requests that differ significantly from our standardised code styles.
|
||||
|
||||
All code is automatically checked by Codacy and our linting process, and will notify you if there are any issues with the code that you submit. We require that code passes these quality checks before merging.
|
||||
|
||||
### PR review process
|
||||
|
||||
At least two members of the Cal.com team should review and approve any PR before it is merged.
|
||||
|
||||
Once two members of the team have approved this, someone from the team will merge the PR. If you are part of the Cal.com team, you should merge your own PRs once you have received both approvals.
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: 'Code Blocks'
|
||||
description: 'Display inline code and code blocks'
|
||||
icon: 'code'
|
||||
---
|
||||
|
||||
## Basic
|
||||
|
||||
### Inline Code
|
||||
|
||||
To denote a `word` or `phrase` as code, enclose it in backticks (`).
|
||||
|
||||
```
|
||||
To denote a `word` or `phrase` as code, enclose it in backticks (`).
|
||||
```
|
||||
|
||||
### Code Block
|
||||
|
||||
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
|
||||
|
||||
```java HelloWorld.java
|
||||
class HelloWorld {
|
||||
public static void main(String[] args) {
|
||||
System.out.println("Hello, World!");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
````md
|
||||
```java HelloWorld.java
|
||||
class HelloWorld {
|
||||
public static void main(String[] args) {
|
||||
System.out.println("Hello, World!");
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: 'Images and Embeds'
|
||||
description: 'Add image, video, and other HTML elements'
|
||||
icon: 'image'
|
||||
---
|
||||
|
||||
<img
|
||||
style={{ borderRadius: '0.5rem' }}
|
||||
src="https://mintlify-assets.b-cdn.net/bigbend.jpg"
|
||||
/>
|
||||
|
||||
## Image
|
||||
|
||||
### Using Markdown
|
||||
|
||||
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
|
||||
|
||||
### Using Embeds
|
||||
|
||||
To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
|
||||
|
||||
```html
|
||||
<img height="200" src="/path/image.jpg" />
|
||||
```
|
||||
|
||||
## Embeds and HTML elements
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.youtube.com/embed/4KzFe50RQkQ"
|
||||
title="YouTube video player"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
style={{ width: '100%', borderRadius: '0.5rem' }}
|
||||
></iframe>
|
||||
|
||||
<br />
|
||||
|
||||
<Tip>
|
||||
|
||||
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
|
||||
|
||||
</Tip>
|
||||
|
||||
### iFrames
|
||||
|
||||
Loads another HTML page within the document. Most commonly used for embedding videos.
|
||||
|
||||
```html
|
||||
<iframe src="https://www.youtube.com/embed/4KzFe50RQkQ"> </iframe>
|
||||
```
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
title: 'Markdown Syntax'
|
||||
description: 'Text, title, and styling in standard markdown'
|
||||
icon: 'text-size'
|
||||
---
|
||||
|
||||
## Titles
|
||||
|
||||
Best used for section headers.
|
||||
|
||||
```md
|
||||
## Titles
|
||||
```
|
||||
|
||||
### Subtitles
|
||||
|
||||
Best use to subsection headers.
|
||||
|
||||
```md
|
||||
### Subtitles
|
||||
```
|
||||
|
||||
<Tip>
|
||||
|
||||
Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
|
||||
|
||||
</Tip>
|
||||
|
||||
## Text Formatting
|
||||
|
||||
We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
|
||||
|
||||
| Style | How to write it | Result |
|
||||
| ------------- | ----------------- | --------------- |
|
||||
| Bold | `**bold**` | **bold** |
|
||||
| Italic | `_italic_` | _italic_ |
|
||||
| Strikethrough | `~strikethrough~` | ~strikethrough~ |
|
||||
|
||||
You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
|
||||
|
||||
You need to use HTML to write superscript and subscript text. That is, add `<sup>` or `<sub>` around your text.
|
||||
|
||||
| Text Size | How to write it | Result |
|
||||
| ----------- | ------------------------ | ---------------------- |
|
||||
| Superscript | `<sup>superscript</sup>` | <sup>superscript</sup> |
|
||||
| Subscript | `<sub>subscript</sub>` | <sub>subscript</sub> |
|
||||
|
||||
## Linking to Pages
|
||||
|
||||
You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
|
||||
|
||||
Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
|
||||
|
||||
Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
|
||||
|
||||
## Blockquotes
|
||||
|
||||
### Singleline
|
||||
|
||||
To create a blockquote, add a `>` in front of a paragraph.
|
||||
|
||||
> Dorothy followed her through many of the beautiful rooms in her castle.
|
||||
|
||||
```md
|
||||
> Dorothy followed her through many of the beautiful rooms in her castle.
|
||||
```
|
||||
|
||||
### Multiline
|
||||
|
||||
> Dorothy followed her through many of the beautiful rooms in her castle.
|
||||
>
|
||||
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
|
||||
|
||||
```md
|
||||
> Dorothy followed her through many of the beautiful rooms in her castle.
|
||||
>
|
||||
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
|
||||
```
|
||||
|
||||
### LaTeX
|
||||
|
||||
Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
|
||||
|
||||
<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>
|
||||
|
||||
```md
|
||||
<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>
|
||||
```
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
title: 'Navigation'
|
||||
description: 'The navigation field in mint.json defines the pages that go in the navigation menu'
|
||||
icon: 'map'
|
||||
---
|
||||
|
||||
The navigation menu is the list of links on every website.
|
||||
|
||||
You will likely update `mint.json` every time you add a new page. Pages do not show up automatically.
|
||||
|
||||
## Navigation syntax
|
||||
|
||||
Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```json Regular Navigation
|
||||
"navigation": [
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": ["quickstart"]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
```json Nested Navigation
|
||||
"navigation": [
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": [
|
||||
"quickstart",
|
||||
{
|
||||
"group": "Nested Reference Pages",
|
||||
"pages": ["nested-reference-page"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
## Folders
|
||||
|
||||
Simply put your MDX files in folders and update the paths in `mint.json`.
|
||||
|
||||
For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
|
||||
|
||||
<Warning>
|
||||
|
||||
You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
|
||||
|
||||
</Warning>
|
||||
|
||||
```json Navigation With Folder
|
||||
"navigation": [
|
||||
{
|
||||
"group": "Group Name",
|
||||
"pages": ["your-folder/your-page"]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Hidden Pages
|
||||
|
||||
MDX files not included in `mint.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
title: Reusable Snippets
|
||||
description: Reusable, custom snippets to keep content in sync
|
||||
icon: 'recycle'
|
||||
---
|
||||
|
||||
import SnippetIntro from '/snippets/snippet-intro.mdx';
|
||||
|
||||
<SnippetIntro />
|
||||
|
||||
## Creating a custom snippet
|
||||
|
||||
**Pre-condition**: You must create your snippet file in the `snippets` directory.
|
||||
|
||||
<Note>
|
||||
Any page in the `snippets` directory will be treated as a snippet and will not
|
||||
be rendered into a standalone page. If you want to create a standalone page
|
||||
from the snippet, import the snippet into another file and call it as a
|
||||
component.
|
||||
</Note>
|
||||
|
||||
### Default export
|
||||
|
||||
1. Add content to your snippet file that you want to re-use across multiple
|
||||
locations. Optionally, you can add variables that can be filled in via props
|
||||
when you import the snippet.
|
||||
|
||||
```mdx snippets/my-snippet.mdx
|
||||
Hello world! This is my content I want to reuse across pages. My keyword of the
|
||||
day is {word}.
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The content that you want to reuse must be inside the `snippets` directory in
|
||||
order for the import to work.
|
||||
</Warning>
|
||||
|
||||
2. Import the snippet into your destination file.
|
||||
|
||||
```mdx destination-file.mdx
|
||||
---
|
||||
title: My title
|
||||
description: My Description
|
||||
---
|
||||
|
||||
import MySnippet from '/snippets/path/to/my-snippet.mdx';
|
||||
|
||||
## Header
|
||||
|
||||
Lorem impsum dolor sit amet.
|
||||
|
||||
<MySnippet word="bananas" />
|
||||
```
|
||||
|
||||
### Reusable variables
|
||||
|
||||
1. Export a variable from your snippet file:
|
||||
|
||||
```mdx snippets/path/to/custom-variables.mdx
|
||||
export const myName = 'my name';
|
||||
|
||||
export const myObject = { fruit: 'strawberries' };
|
||||
```
|
||||
|
||||
2. Import the snippet from your destination file and use the variable:
|
||||
|
||||
```mdx destination-file.mdx
|
||||
---
|
||||
title: My title
|
||||
description: My Description
|
||||
---
|
||||
|
||||
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
|
||||
|
||||
Hello, my name is {myName} and I like {myObject.fruit}.
|
||||
```
|
||||
|
||||
### Reusable components
|
||||
|
||||
1. Inside your snippet file, create a component that takes in props by exporting
|
||||
your component in the form of an arrow function.
|
||||
|
||||
```mdx snippets/custom-component.mdx
|
||||
export const MyComponent = ({ title }) => (
|
||||
<div>
|
||||
<h1>{title}</h1>
|
||||
<p>... snippet content ...</p>
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
<Warning>
|
||||
MDX does not compile inside the body of an arrow function. Stick to HTML
|
||||
syntax when you can or use a default export if you need to use MDX.
|
||||
</Warning>
|
||||
|
||||
2. Import the snippet into your destination file and pass in the props
|
||||
|
||||
```mdx destination-file.mdx
|
||||
---
|
||||
title: My title
|
||||
description: My Description
|
||||
---
|
||||
|
||||
import { MyComponent } from '/snippets/custom-component.mdx';
|
||||
|
||||
Lorem ipsum dolor sit amet.
|
||||
|
||||
<MyComponent title={'Custom title'} />
|
||||
```
|
||||
@@ -1,318 +0,0 @@
|
||||
---
|
||||
title: 'Global Settings'
|
||||
description: 'Mintlify gives you complete control over the look and feel of your documentation using the mint.json file'
|
||||
icon: 'gear'
|
||||
---
|
||||
|
||||
Every Mintlify site needs a `mint.json` file with the core configuration settings. Learn more about the [properties](#properties) below.
|
||||
|
||||
## Properties
|
||||
|
||||
<ResponseField name="name" type="string" required>
|
||||
Name of your project. Used for the global title.
|
||||
|
||||
Example: `mintlify`
|
||||
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="navigation" type="Navigation[]" required>
|
||||
An array of groups with all the pages within that group
|
||||
<Expandable title="Navigation">
|
||||
<ResponseField name="group" type="string">
|
||||
The name of the group.
|
||||
|
||||
Example: `Settings`
|
||||
|
||||
</ResponseField>
|
||||
<ResponseField name="pages" type="string[]">
|
||||
The relative paths to the markdown files that will serve as pages.
|
||||
|
||||
Example: `["customization", "page"]`
|
||||
|
||||
</ResponseField>
|
||||
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="logo" type="string or object">
|
||||
Path to logo image or object with path to "light" and "dark" mode logo images
|
||||
<Expandable title="Logo">
|
||||
<ResponseField name="light" type="string">
|
||||
Path to the logo in light mode
|
||||
</ResponseField>
|
||||
<ResponseField name="dark" type="string">
|
||||
Path to the logo in dark mode
|
||||
</ResponseField>
|
||||
<ResponseField name="href" type="string" default="/">
|
||||
Where clicking on the logo links you to
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="favicon" type="string">
|
||||
Path to the favicon image
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="colors" type="Colors">
|
||||
Hex color codes for your global theme
|
||||
<Expandable title="Colors">
|
||||
<ResponseField name="primary" type="string" required>
|
||||
The primary color. Used for most often for highlighted content, section
|
||||
headers, accents, in light mode
|
||||
</ResponseField>
|
||||
<ResponseField name="light" type="string">
|
||||
The primary color for dark mode. Used for most often for highlighted
|
||||
content, section headers, accents, in dark mode
|
||||
</ResponseField>
|
||||
<ResponseField name="dark" type="string">
|
||||
The primary color for important buttons
|
||||
</ResponseField>
|
||||
<ResponseField name="background" type="object">
|
||||
The color of the background in both light and dark mode
|
||||
<Expandable title="Object">
|
||||
<ResponseField name="light" type="string" required>
|
||||
The hex color code of the background in light mode
|
||||
</ResponseField>
|
||||
<ResponseField name="dark" type="string" required>
|
||||
The hex color code of the background in dark mode
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="topbarLinks" type="TopbarLink[]">
|
||||
Array of `name`s and `url`s of links you want to include in the topbar
|
||||
<Expandable title="TopbarLink">
|
||||
<ResponseField name="name" type="string">
|
||||
The name of the button.
|
||||
|
||||
Example: `Contact us`
|
||||
</ResponseField>
|
||||
<ResponseField name="url" type="string">
|
||||
The url once you click on the button. Example: `https://mintlify.com/contact`
|
||||
</ResponseField>
|
||||
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="topbarCtaButton" type="Call to Action">
|
||||
<Expandable title="Topbar Call to Action">
|
||||
<ResponseField name="type" type={'"link" or "github"'} default="link">
|
||||
Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
|
||||
</ResponseField>
|
||||
<ResponseField name="url" type="string">
|
||||
If `link`: What the button links to.
|
||||
|
||||
If `github`: Link to the repository to load GitHub information from.
|
||||
</ResponseField>
|
||||
<ResponseField name="name" type="string">
|
||||
Text inside the button. Only required if `type` is a `link`.
|
||||
</ResponseField>
|
||||
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="versions" type="string[]">
|
||||
Array of version names. Only use this if you want to show different versions
|
||||
of docs with a dropdown in the navigation bar.
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="anchors" type="Anchor[]">
|
||||
An array of the anchors, includes the `icon`, `color`, and `url`.
|
||||
<Expandable title="Anchor">
|
||||
<ResponseField name="icon" type="string">
|
||||
The [Font Awesome](https://fontawesome.com/search?s=brands%2Cduotone) icon used to feature the anchor.
|
||||
|
||||
Example: `comments`
|
||||
</ResponseField>
|
||||
<ResponseField name="name" type="string">
|
||||
The name of the anchor label.
|
||||
|
||||
Example: `Community`
|
||||
</ResponseField>
|
||||
<ResponseField name="url" type="string">
|
||||
The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
|
||||
</ResponseField>
|
||||
<ResponseField name="color" type="string">
|
||||
The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
|
||||
</ResponseField>
|
||||
<ResponseField name="version" type="string">
|
||||
Used if you want to hide an anchor until the correct docs version is selected.
|
||||
</ResponseField>
|
||||
<ResponseField name="isDefaultHidden" type="boolean" default="false">
|
||||
Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
|
||||
</ResponseField>
|
||||
<ResponseField name="iconType" default="duotone" type="string">
|
||||
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
|
||||
</ResponseField>
|
||||
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="topAnchor" type="Object">
|
||||
Override the default configurations for the top-most anchor.
|
||||
<Expandable title="Object">
|
||||
<ResponseField name="name" default="Documentation" type="string">
|
||||
The name of the top-most anchor
|
||||
</ResponseField>
|
||||
<ResponseField name="icon" default="book-open" type="string">
|
||||
Font Awesome icon.
|
||||
</ResponseField>
|
||||
<ResponseField name="iconType" default="duotone" type="string">
|
||||
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="tabs" type="Tabs[]">
|
||||
An array of navigational tabs.
|
||||
<Expandable title="Tabs">
|
||||
<ResponseField name="name" type="string">
|
||||
The name of the tab label.
|
||||
</ResponseField>
|
||||
<ResponseField name="url" type="string">
|
||||
The start of the URL that marks what pages go in the tab. Generally, this
|
||||
is the name of the folder you put your pages in.
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="api" type="API">
|
||||
Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
|
||||
<Expandable title="API">
|
||||
<ResponseField name="baseUrl" type="string">
|
||||
The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
|
||||
options that the user can toggle.
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="auth" type="Auth">
|
||||
<Expandable title="Auth">
|
||||
<ResponseField name="method" type='"bearer" | "basic" | "key"'>
|
||||
The authentication strategy used for all API endpoints.
|
||||
</ResponseField>
|
||||
<ResponseField name="name" type="string">
|
||||
The name of the authentication parameter used in the API playground.
|
||||
|
||||
If method is `basic`, the format should be `[usernameName]:[passwordName]`
|
||||
</ResponseField>
|
||||
<ResponseField name="inputPrefix" type="string">
|
||||
The default value that's designed to be a prefix for the authentication input field.
|
||||
|
||||
E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="playground" type="Playground">
|
||||
Configurations for the API playground
|
||||
|
||||
<Expandable title="Playground">
|
||||
<ResponseField name="mode" default="show" type='"show" | "simple" | "hide"'>
|
||||
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
|
||||
|
||||
Learn more at the [playground guides](/api-playground/demo)
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="maintainOrder" type="boolean">
|
||||
Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
|
||||
|
||||
<Warning>This behavior will soon be enabled by default, at which point this field will be deprecated.</Warning>
|
||||
</ResponseField>
|
||||
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="openapi" type="string | string[]">
|
||||
A string or an array of strings of URL(s) or relative path(s) pointing to your
|
||||
OpenAPI file.
|
||||
|
||||
Examples:
|
||||
<CodeGroup>
|
||||
```json Absolute
|
||||
"openapi": "https://example.com/openapi.json"
|
||||
```
|
||||
```json Relative
|
||||
"openapi": "/openapi.json"
|
||||
```
|
||||
```json Multiple
|
||||
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="footerSocials" type="FooterSocials">
|
||||
An object of social media accounts where the key:property pair represents the social media platform and the account url.
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"x": "https://x.com/mintlify",
|
||||
"website": "https://mintlify.com"
|
||||
}
|
||||
```
|
||||
<Expandable title="FooterSocials">
|
||||
<ResponseField name="[key]" type="string">
|
||||
One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
|
||||
|
||||
Example: `x`
|
||||
</ResponseField>
|
||||
<ResponseField name="property" type="string">
|
||||
The URL to the social platform.
|
||||
|
||||
Example: `https://x.com/mintlify`
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="feedback" type="Feedback">
|
||||
Configurations to enable feedback buttons
|
||||
|
||||
<Expandable title="Feedback">
|
||||
<ResponseField name="suggestEdit" type="boolean" default="false">
|
||||
Enables a button to allow users to suggest edits via pull requests
|
||||
</ResponseField>
|
||||
<ResponseField name="raiseIssue" type="boolean" default="false">
|
||||
Enables a button to allow users to raise an issue about the documentation
|
||||
</ResponseField>
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="modeToggle" type="ModeToggle">
|
||||
Customize the dark mode toggle.
|
||||
<Expandable title="ModeToggle">
|
||||
<ResponseField name="default" type={'"light" or "dark"'}>
|
||||
Set if you always want to show light or dark mode for new users. When not
|
||||
set, we default to the same mode as the user's operating system.
|
||||
</ResponseField>
|
||||
<ResponseField name="isHidden" type="boolean" default="false">
|
||||
Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
|
||||
|
||||
<CodeGroup>
|
||||
```json Only Dark Mode
|
||||
"modeToggle": {
|
||||
"default": "dark",
|
||||
"isHidden": true
|
||||
}
|
||||
```
|
||||
|
||||
```json Only Light Mode
|
||||
"modeToggle": {
|
||||
"default": "light",
|
||||
"isHidden": true
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
</ResponseField>
|
||||
|
||||
</Expandable>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="backgroundImage" type="string">
|
||||
A background image to be displayed behind every page. See example with
|
||||
[Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
|
||||
</ResponseField>
|
||||
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="79" height="20" role="img" aria-label="High Priority"><title>High Priority</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="79" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#fe7d37"/><rect x="0" width="79" height="20" fill="#fe7d37"/><rect width="79" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="395" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="690">High Priority</text><text x="395" y="140" transform="scale(.1)" fill="#fff" textLength="690">High Priority</text></g></svg>
|
||||
|
After Width: | Height: | Size: 939 B |
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="75" height="20" role="img" aria-label="Low Priority"><title>Low Priority</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="75" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#97ca00"/><rect x="0" width="75" height="20" fill="#97ca00"/><rect width="75" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="375" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="650">Low Priority</text><text x="375" y="140" transform="scale(.1)" fill="#fff" textLength="650">Low Priority</text></g></svg>
|
||||
|
After Width: | Height: | Size: 935 B |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="97" height="20" role="img" aria-label="Medium Priority"><title>Medium Priority</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="97" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#dfb317"/><rect x="0" width="97" height="20" fill="#dfb317"/><rect width="97" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="485" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="870">Medium Priority</text><text x="485" y="140" transform="scale(.1)" fill="#fff" textLength="870">Medium Priority</text></g></svg>
|
||||
|
After Width: | Height: | Size: 947 B |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="47" height="20" role="img" aria-label="Urgent"><title>Urgent</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="47" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#e05d44"/><rect x="0" width="47" height="20" fill="#e05d44"/><rect width="47" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="235" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">Urgent</text><text x="235" y="140" transform="scale(.1)" fill="#fff" textLength="370">Urgent</text></g></svg>
|
||||
|
After Width: | Height: | Size: 911 B |
+146
-2
@@ -32,6 +32,18 @@
|
||||
"url": "https://app.cal.com"
|
||||
},
|
||||
"tabs": [
|
||||
{
|
||||
"name": "Developing",
|
||||
"url": "developing"
|
||||
},
|
||||
{
|
||||
"name": "Self Hosting",
|
||||
"url": "self-hosting"
|
||||
},
|
||||
{
|
||||
"name": "Platform",
|
||||
"url": "platform"
|
||||
},
|
||||
{
|
||||
"name": "API v2 Reference",
|
||||
"openapi": "/api-reference/v2/openapi.json",
|
||||
@@ -45,11 +57,138 @@
|
||||
],
|
||||
"navigation": [
|
||||
{
|
||||
"group": "Getting started",
|
||||
"group": "Getting Started",
|
||||
"pages": ["developing/introduction", "developing/local-development"]
|
||||
},
|
||||
{
|
||||
"group": "Open Source Contribution",
|
||||
"pages": [
|
||||
"developing/open-source-contribution/index",
|
||||
"developing/open-source-contribution/code-styling",
|
||||
"developing/open-source-contribution/pull-requests",
|
||||
"developing/open-source-contribution/contributors-guide"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Guides",
|
||||
"pages": [
|
||||
{
|
||||
"group": "API Development",
|
||||
"icon": "brackets-curly",
|
||||
"pages": ["developing/guides/api/how-to-setup-api-in-a-local-instance"]
|
||||
},
|
||||
{
|
||||
"group": "App Store and Integration",
|
||||
"icon": "grid",
|
||||
"pages": [
|
||||
"developing/guides/appstore-and-integration/adding-your-first-app",
|
||||
"developing/guides/appstore-and-integration/build-a-greeter-app",
|
||||
"developing/guides/appstore-and-integration/build-an-app",
|
||||
"developing/guides/appstore-and-integration/how-to-show-assigned-people-from-a-crm",
|
||||
"developing/guides/appstore-and-integration/integration-with-hubspot",
|
||||
"developing/guides/appstore-and-integration/oauth"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Auth and Provision",
|
||||
"icon": "user-shield",
|
||||
"pages": [
|
||||
"developing/guides/auth-and-provision/how-to-setup-oidc-with-okta",
|
||||
"developing/guides/auth-and-provision/how-to-setup-scim-with-okta",
|
||||
"developing/guides/auth-and-provision/sso-setup"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Email",
|
||||
"icon": "inbox",
|
||||
"pages": ["developing/guides/email/setup-mailtrap-for-email-testing"]
|
||||
},
|
||||
{
|
||||
"group": "Embeds",
|
||||
"icon": "code-simple",
|
||||
"pages": ["developing/guides/embeds/embed-events"]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": [
|
||||
"self-hosting/installation",
|
||||
"self-hosting/database-migrations",
|
||||
"self-hosting/upgrading",
|
||||
"self-hosting/sso-setup",
|
||||
"self-hosting/docker"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Deployments",
|
||||
"pages": [
|
||||
"self-hosting/deployments/aws",
|
||||
"self-hosting/deployments/azure",
|
||||
"self-hosting/deployments/gcp",
|
||||
"self-hosting/deployments/vercel"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Apps",
|
||||
"pages": [
|
||||
{
|
||||
"group": "Install Apps",
|
||||
"icon": "grid-2-plus",
|
||||
"pages": [
|
||||
"self-hosting/apps/install-apps/introduction",
|
||||
"self-hosting/apps/install-apps/google",
|
||||
"self-hosting/apps/install-apps/microsoft",
|
||||
"self-hosting/apps/install-apps/zoom",
|
||||
"self-hosting/apps/install-apps/daily",
|
||||
"self-hosting/apps/install-apps/hubspot",
|
||||
"self-hosting/apps/install-apps/sendgrid",
|
||||
"self-hosting/apps/install-apps/stripe",
|
||||
"self-hosting/apps/install-apps/twilio",
|
||||
"self-hosting/apps/install-apps/zoho"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Guides",
|
||||
"pages": [
|
||||
{
|
||||
"group": "App Store and Integration",
|
||||
"icon": "grid",
|
||||
"pages": ["/self-hosting/guides/appstore-and-integration/syncing-third-party-apps"]
|
||||
},
|
||||
{
|
||||
"group": "White Labeling",
|
||||
"icon": "tag",
|
||||
"pages": [
|
||||
"/self-hosting/guides/white-labeling/introduction",
|
||||
"/self-hosting/guides/white-labeling/custom-css"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Sponsorship",
|
||||
"icon": "money-check-dollar",
|
||||
"pages": ["/self-hosting/guides/sponsorship/can-calcom-sponsor-my-open-source-project"]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": [
|
||||
"platform/introduction",
|
||||
"platform/quickstart",
|
||||
"platform/booking-redirects",
|
||||
"platform/atoms-reference",
|
||||
"platform/faq"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": ["api-reference/v2/introduction", "api-reference/v2/v1-v2-differences"]
|
||||
},
|
||||
{
|
||||
"group": "Getting started",
|
||||
"group": "Getting Started",
|
||||
"pages": [
|
||||
"api-reference/v1/introduction",
|
||||
"api-reference/v1/authentication",
|
||||
@@ -62,5 +201,10 @@
|
||||
"x": "https://x.com/calcom",
|
||||
"github": "https://github.com/calcom",
|
||||
"linkedin": "https://www.linkedin.com/company/cal-com"
|
||||
},
|
||||
"feedback": {
|
||||
"thumbsRating": true,
|
||||
"suggestEdit": true,
|
||||
"raiseIssue": true
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,231 @@
|
||||
---
|
||||
title: Atoms reference
|
||||
description: Everything related to atoms from props to styling.
|
||||
---
|
||||
|
||||
## Props
|
||||
|
||||
Below is a list of tables that contains all the available props each atom contains.
|
||||
|
||||
<Info>Please ensure all custom classnames are valid [Tailwind CSS](https://tailwindcss.com/) classnames.</Info>
|
||||
|
||||
### 1. Google calendar connect atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:--------------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
||||
| className | No | To pass in custom classnames from outside for styling the atom |
|
||||
| label | No | The label for the connect button |
|
||||
| alreadyConnectedLabel | No | Label to display when atom is in already connected state |
|
||||
| loadingLabel | No | Label to display when atom is in loading state |
|
||||
| onCheckError | No | A callback function to handle errors when checking the connection status |
|
||||
|
||||
|
||||
### 2. Outlook calendar connect atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:--------------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
||||
| className | No | To pass in custom classnames from outside for styling the atom |
|
||||
| label | No | The label for the connect button |
|
||||
| alreadyConnectedLabel | No | Label to display when atom is in already connected state |
|
||||
| loadingLabel | No | Label to display when atom is in loading state |
|
||||
| onCheckError | No | A callback function to handle errors when checking the connection status |
|
||||
| redir | No | A custom redirect URL link where the user gets redirected after successful authentication |
|
||||
|
||||
|
||||
### 3. Apple calendar connect atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:--------------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
||||
| className | No | To pass in custom classnames from outside for styling the atom |
|
||||
| label | No | The label for the connect button |
|
||||
| alreadyConnectedLabel | No | Label to display when atom is in already connected state |
|
||||
| loadingLabel | No | Label to display when atom is in loading state |
|
||||
| onCheckError | No | A callback function to handle errors when checking the connection status |
|
||||
|
||||
|
||||
### 4. Availability settings atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:--------------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
||||
| id | No | The ID of the schedule which fetches a user's availability |
|
||||
| labels | No | Helpful if you want to pass in custom labels for i18n |
|
||||
| customClassNames | No | To pass in custom classnames from outside for styling the atom |
|
||||
| onUpdateSuccess | No | A callback function to handle updating user availability successfully |
|
||||
| onBeforeUpdate | No | Validates schedule before it is sent to the server; if true, the schedule is sent, else it is not |
|
||||
| onUpdateError | No | A callback function that gets triggered when the user availability fails to update |
|
||||
| onDeleteSuccess | No | A callback function that gets triggered when the user availability is deleted successfully |
|
||||
| onDeleteError | No | A callback function that gets triggered when the user availability fails to delete |
|
||||
| enableOverrides | No | Allows user to enable or disable date overrides display in the atom; defaults to disabled |
|
||||
|
||||
|
||||
### 5. Booker atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:----------------------------|:----------|:-------------------------------------------------------------------------------------------------------|
|
||||
| username | Yes | Username of the person whose schedule is to be displayed |
|
||||
| eventSlug | Yes | Unique slug created for a particular event |
|
||||
| orgBannerUrl | No | URL of the user's current organization |
|
||||
| customClassNames | No | To pass in custom classnames from outside for styling the atom |
|
||||
| month | No | The exact month for displaying a user's availability; defaults to the current month |
|
||||
| selectedDate | No | Default selected date for which the slot picker opens |
|
||||
| hideBranding | No | For hiding any branding on the booker |
|
||||
| isAway | No | Sets the booker component to the away state |
|
||||
| allowsDynamicBooking | No | Boolean indicating if the booking is a dynamic booking |
|
||||
| bookingData | No | Data for rescheduling a booking passed in via this prop |
|
||||
| defaultFormValues | No | Prefilled values for booking form fields like name, email, guests, notes, reschedule reason, etc. |
|
||||
| isTeamEvent | No | Boolean indicating if it is a team event |
|
||||
| duration | No | Refers to a multiple-duration event type; selects default if not passed |
|
||||
| durationConfig | No | Configures selectable options for a multi-duration event type |
|
||||
| hashedLink | No | Refers to the private link from event types page |
|
||||
| isInstantMeeting | No | Boolean indicating if the booking is an instant meeting |
|
||||
| rescheduleUid | No | Unique ID generated during rescheduling |
|
||||
| bookingUid | No | Unique ID generated during booking |
|
||||
| locationUrl | No | Custom meeting link URL instead of a Cal.com link |
|
||||
| firstName | No | First name of the attendee |
|
||||
| lastName | No | Last name of the attendee |
|
||||
| guests | No | Invite a guest to join a meeting |
|
||||
| name | No | Host name |
|
||||
| onCreateBookingSuccess | No | Callback function for successful booking creation |
|
||||
| onCreateBookingError | No | Callback function triggered on booking creation failure |
|
||||
| onCreateRecurringBookingSuccess | No | Callback function for successful recurring booking creation |
|
||||
| onCreateRecurringBookingError | No | Callback function triggered on recurring booking creation failure |
|
||||
| onCreateInstantBookingSuccess | No | Callback function for successful instant booking creation |
|
||||
| onCreateInstantBookingError | No | Callback function triggered on instant booking creation failure |
|
||||
| onReserveSlotSuccess | No | Callback function for successful slot reservation |
|
||||
| onReserveSlotError | No | Callback function triggered on slot reservation failure |
|
||||
| onDeleteSlotSuccess | No | Callback function for successful slot deletion |
|
||||
| onDeleteSlotError | No | Callback function triggered on slot deletion failure |
|
||||
|
||||
|
||||
<Info>Booker embed atom shares the same prop interface as the Booker atom. Hence, you can pass in the same props to both the Booker Embed atom and the Booker atom.</Info>
|
||||
|
||||
### 6. Calendar settings atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
||||
| classNames | No | To pass in custom classnames from outside for styling the atom |
|
||||
|
||||
|
||||
### 7. Destination calendar settings atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
||||
| statusLoader | No | To pass in a custom component for the loading state |
|
||||
| classNames | No | To pass in custom classnames from outside for styling the atom |
|
||||
|
||||
|
||||
### 8. Selected calendar settings atom
|
||||
<p></p>
|
||||
|
||||
| Name | Required | Description |
|
||||
|:------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
||||
| classNames | No | To pass in custom classnames from outside for styling the atom |
|
||||
|
||||
|
||||
## Styling
|
||||
|
||||
Below is a list of tables that contains all the available classnames that can be used for each atom.
|
||||
|
||||
### 1. Google calendar connect atom
|
||||
<p></p>
|
||||
|
||||
| Name | Description |
|
||||
|:------------|:-----------------------------------------------------|
|
||||
| className | Pass in custom classnames from outside for styling the button |
|
||||
|
||||
|
||||
### 2. Outlook calendar connect atom
|
||||
<p></p>
|
||||
|
||||
| Name | Description |
|
||||
|:------------|:-----------------------------------------------------|
|
||||
| className | Pass in custom classnames from outside for styling the button |
|
||||
|
||||
|
||||
### 3. Apple calendar connect atom
|
||||
<p></p>
|
||||
|
||||
| Name | Description |
|
||||
|:------------|:-----------------------------------------------------|
|
||||
| className | Pass in custom classnames from outside for styling the button |
|
||||
|
||||
|
||||
### 4. Availability settings atom
|
||||
<p></p>
|
||||
|
||||
Availability settings atom accepts custom styles via the **customClassNames** prop. All the props that we see below fall under this **customClassNames** prop.
|
||||
|
||||
| Name | Description |
|
||||
|:---------------------------|:-----------------------------------------------------------------------|
|
||||
| containerClassName | Adds styling to the whole availability settings component |
|
||||
| ctaClassName | Adds stylings only to certain call-to-action buttons |
|
||||
| editableHeadingClassName | Editable heading or title can be styled |
|
||||
| formClassName | Form which contains the days and toggles |
|
||||
| timezoneSelectClassName | Adds styling to the timezone select component |
|
||||
| subtitlesClassName | Styles the subtitle |
|
||||
| scheduleContainer | Styles the entire schedule component |
|
||||
| scheduleDay | Adds styling to just the day of a particular schedule |
|
||||
| dayRanges | Adds styling to day ranges |
|
||||
| timeRanges | Time ranges in the availability settings can be customized |
|
||||
| labelAndSwitchContainer | Adds styling to label and switches |
|
||||
| overridesModalClassNames | Adds styling to the date overrides modal |
|
||||
|
||||
|
||||
### 5. Booker atom
|
||||
<p></p>
|
||||
|
||||
Booker atom accepts custom styles via the **customClassNames** prop. All the props that we see below fall under this **customClassNames** prop. In terms of styling there are four major classnames for the Booker, i.e. **bookerContainer**, **eventMetaCustomClassNames**, **datePickerCustomClassNames** and **availableTimeSlotsCustomClassNames**. Most of the classnames below fall under one of these sub classes.
|
||||
|
||||
| Name | Description |
|
||||
|:-----------------------------|:----------------------------------------------------------------------|
|
||||
| bookerContainer | Adds styling to the whole of the booker atom |
|
||||
| eventMetaContainer | Styles the event meta component containing details about an event |
|
||||
| eventMetaTitle | Adds styles to the event meta title |
|
||||
| eventMetaTimezoneSelect | Adds styles to the event meta timezone selector |
|
||||
| datePickerContainer | Adds styling to the date picker |
|
||||
| datePickerTitle | Styles the date picker title |
|
||||
| datePickerDays | Adds styling to all days in the date picker |
|
||||
| datePickerDate | Adds styling to all dates in the date picker |
|
||||
| datePickerDatesActive | Styles only the dates with available slots |
|
||||
| datePickerToggle | Styles the left and right toggle buttons |
|
||||
| availableTimeSlotsContainer | Adds styling to the available time slots component |
|
||||
| availableTimeSlotsHeaderContainer | Styles only the header container |
|
||||
| availableTimeSlotsTitle | Adds styles to the title |
|
||||
| availableTimeSlotsTimeFormatToggle | Adds styles to the format toggle buttons |
|
||||
| availableTimes | Styles all the available times container |
|
||||
|
||||
|
||||
### 6. Calendar settings atom
|
||||
<p></p>
|
||||
|
||||
| Name | Description |
|
||||
|:-----------------------------------------|:--------------------------------------------------------------|
|
||||
| calendarSettingsCustomClassnames | Adds styling to the entire calendar settings atom |
|
||||
| destinationCalendarSettingsCustomClassnames | Adds styling only to the destination calendar container |
|
||||
| selectedCalendarSettingsCustomClassnames | Adds styling only to the selected calendar container |
|
||||
|
||||
|
||||
### 7. Destination calendar settings atom
|
||||
<p></p>
|
||||
|
||||
| Name | Description |
|
||||
|:------------|:-----------------------------------------------------|
|
||||
| classNames | Pass in custom classnames from outside for styling the atom |
|
||||
|
||||
|
||||
### 8. Selected calendar settings atom
|
||||
<p></p>
|
||||
|
||||
| Name | Description |
|
||||
|:------------|:-----------------------------------------------------|
|
||||
| classNames | Pass in custom classnames from outside for styling the atom |
|
||||
|
||||
|
||||
<Note>Please note that sometimes the custom classnames may fail to override the styling with the classnames that you might have passed via props. That is because the **clsx** utility function that we use to override classnames inside our components has some limitations. A simple get around to solve this issue is to just prefix your classnames with **!** property just before passing in any classname.</Note>
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "Daily"
|
||||
---
|
||||
|
||||
#### Obtaining Daily API Credentials
|
||||
<Steps>
|
||||
<Step title="Open Daily and sign into your account">
|
||||
Go to [Daily](https://www.daily.co/) and sign into your account.
|
||||
</Step>
|
||||
<Step title="Navigate to the Developers tab">
|
||||
From within your dashboard, go to the [developers](https://dashboard.daily.co/developers) tab.
|
||||
</Step>
|
||||
<Step title="Copy your API key">
|
||||
Copy the API key provided in the developers tab.
|
||||
</Step>
|
||||
<Step title="Paste the API key into the .env file">
|
||||
Now paste the API key into the `DAILY_API_KEY` field in your `.env` file.
|
||||
</Step>
|
||||
<Step title="Set the DAILY_SCALE_PLAN variable (optional)">
|
||||
If you have the [Daily Scale Plan](https://www.daily.co/pricing), set the `DAILY_SCALE_PLAN` variable to `true` in the `.env` file to use features like video recording.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "Google"
|
||||
---
|
||||
#### Obtaining the Google API Credentials
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Google API Console">
|
||||
Go to [Google API Console](https://console.cloud.google.com/apis/dashboard). If you don't have a project in your Google Cloud subscription, create one before proceeding. Under the Dashboard pane, select "Enable APIs and Services".
|
||||
</Step>
|
||||
<Step title="Search for the Google Calendar API">
|
||||
In the search box, type "calendar" and select the Google Calendar API search result.
|
||||
</Step>
|
||||
<Step title="Enable the Google Calendar API">
|
||||
Enable the selected API to proceed.
|
||||
</Step>
|
||||
<Step title="Configure the OAuth Consent Screen">
|
||||
Go to the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) from the side pane. Select the app type (Internal or External) and enter the basic app details on the first page.
|
||||
</Step>
|
||||
<Step title="Add Calendar Scopes">
|
||||
On the Scopes page, select "Add or Remove Scopes". Search for Calendar.event and select the scopes with values `.../auth/calendar.events`, `.../auth/calendar.readonly`, and then click "Update".
|
||||
</Step>
|
||||
<Step title="Add Test Users">
|
||||
On the Test Users page, add the Google account(s) you'll be using. Verify details on the last page to complete the consent screen configuration.
|
||||
</Step>
|
||||
<Step title="Create OAuth Credentials">
|
||||
From the side pane, select [Credentials](https://console.cloud.google.com/apis/credentials) and then "Create Credentials". Choose "OAuth Client ID".
|
||||
</Step>
|
||||
<Step title="Select Web Application as the Application Type">
|
||||
Choose "Web Application" as the Application Type.
|
||||
</Step>
|
||||
<Step title="Add Authorized Redirect URIs">
|
||||
Under Authorized redirect URI's, add the URIs:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/googlecalendar/callback
|
||||
<Cal.com URL>/api/auth/callback/google
|
||||
```
|
||||
Replace `<Cal.com URL>` with the URL where your application runs.
|
||||
</Step>
|
||||
<Step title="Download the OAuth Client ID JSON">
|
||||
The key will be created, redirecting you back to the Credentials page. Select the new client ID under "OAuth 2.0 Client IDs", then click "Download JSON". Copy the JSON file contents and paste the entire string into the `.env` and `.env.appStore` files under the `GOOGLE_API_CREDENTIALS` key.
|
||||
</Step>
|
||||
<Step title="Set the Google Integration as Internal">
|
||||
In the `.env` file, set the following environment variable:
|
||||
```
|
||||
GOOGLE_LOGIN_ENABLED=false
|
||||
```
|
||||
This will configure the Google integration as an Internal app, restricting login access.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### **Adding Google Calendar to Cal.com App Store**
|
||||
|
||||
After adding Google credentials, you can now add the Google Calendar App to the app store. Repopulate the App store by running:
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "HubSpot"
|
||||
---
|
||||
### Obtaining HubSpot Client ID and Secret
|
||||
|
||||
<Steps>
|
||||
<Step title="Sign into HubSpot Developer">
|
||||
Go to [HubSpot Developer](https://developer.hubspot.com/) and sign into your account, or create a new one.
|
||||
</Step>
|
||||
<Step title="Navigate to Manage Apps">
|
||||
From the Developer account home page, go to "Manage apps".
|
||||
</Step>
|
||||
<Step title="Create a new app">
|
||||
Click the "Create app" button located at the top right corner of the page.
|
||||
</Step>
|
||||
<Step title="Fill in App Information">
|
||||
In the "App info" tab, fill in any information you want for your app.
|
||||
</Step>
|
||||
<Step title="Go to the Auth tab">
|
||||
Navigate to the "Auth" tab to set up authentication for the app.
|
||||
</Step>
|
||||
<Step title="Copy Client ID and Client Secret">
|
||||
Copy the Client ID and Client Secret and add them to your `.env` file under the fields:
|
||||
```
|
||||
HUBSPOT_CLIENT_ID
|
||||
HUBSPOT_CLIENT_SECRET
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set the Redirect URL for OAuth">
|
||||
Set the Redirect URL for OAuth to:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/hubspot/callback
|
||||
```
|
||||
Replace `<Cal.com URL>` with the URL where your application is hosted.
|
||||
</Step>
|
||||
<Step title="Select Required Scopes">
|
||||
In the "Scopes" section, select "Read" and "Write" for the scope called `crm.objects.contacts`.
|
||||
</Step>
|
||||
<Step title="Save the Application">
|
||||
Click the "Save" button at the bottom of the page.
|
||||
</Step>
|
||||
<Step title="Complete HubSpot Integration">
|
||||
You’re all set! Any booking in Cal.com will now be created as a meeting in HubSpot for your contacts.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: "Introduction"
|
||||
---
|
||||
|
||||
Install desired apps in your self-hosted instance for better integration.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card href="/self-hosting/install-apps/google" title="Google" icon="google">
|
||||
Install google for supporting Google Calendar and Google Meet integrations
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/microsoft" title="Microsoft" icon="microsoft">
|
||||
Install microsoft to support Exchange365 integration
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/zoom" title="Zoom" icon="z">
|
||||
Install Zoom to support Zoom video conferencing integration
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/daily" title="Daily" icon="video">
|
||||
Install Daily to support Cal Video integration
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/hubspot" title="Hubspot" icon="hubspot">
|
||||
Install Hubspot to support Hubspot CRM integration
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/sendgrid" title="Sendgrid" icon="envelope">
|
||||
Install Sendgrid to support Sendgrid Email integration
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/stripe" title="Stripe" icon="stripe">
|
||||
Install Stripe to support Stripe integration for paid bookings
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/twilio" title="Twilio" icon="grid-round-2" iconType="solid">
|
||||
Install Twilio to support Workflows integration for sms reminders
|
||||
</Card>
|
||||
<Card href="/self-hosting/install-apps/zoho" title="Zoho" icon="square-dashed">
|
||||
Install Zoho to support Zoho CRM integration
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "Microsoft"
|
||||
---
|
||||
#### Obtaining Microsoft Graph Client ID and Secret
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Azure App Registration">
|
||||
Go to [Azure App Registration](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) and select "New registration".
|
||||
</Step>
|
||||
<Step title="Name your application">
|
||||
Provide a name for your application to proceed with the registration.
|
||||
</Step>
|
||||
<Step title="Set who can use this application">
|
||||
Set **Who can use this application or access this API?** to **Accounts in any organizational directory (Any Azure AD directory - Multitenant)**.
|
||||
</Step>
|
||||
<Step title="Configure the Web redirect URI">
|
||||
Set the **Web** redirect URI to:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/office365calendar/callback
|
||||
```
|
||||
Replace `<Cal.com URL>` with the URL where your application runs.
|
||||
</Step>
|
||||
<Step title="Obtain and set the MS_GRAPH_CLIENT_ID">
|
||||
Use the **Application (client) ID** as the value for **MS_GRAPH_CLIENT_ID** in your `.env` file.
|
||||
</Step>
|
||||
<Step title="Create a client secret and set MS_GRAPH_CLIENT_SECRET">
|
||||
Click on **Certificates & secrets**, create a new client secret, and use the generated value as the **MS_GRAPH_CLIENT_SECRET** in your `.env` file.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: "Sendgrid"
|
||||
---
|
||||
<Steps>
|
||||
<Step title="Create a SendGrid account">
|
||||
Go to [https://signup.sendgrid.com/](https://signup.sendgrid.com/) and create a new SendGrid account.
|
||||
</Step>
|
||||
<Step title="Generate an API key">
|
||||
Navigate to **Settings** -> **API Keys** and create a new API key.
|
||||
</Step>
|
||||
<Step title="Add API key to .env">
|
||||
Copy the generated API key and add it to your `.env` file under the field:
|
||||
```
|
||||
SENDGRID_API_KEY
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify a sender email">
|
||||
Go to **Settings** -> **Sender Authentication** and verify a single sender.
|
||||
</Step>
|
||||
<Step title="Add verified email to .env">
|
||||
Copy the verified email address and add it to your `.env` file under the field:
|
||||
```
|
||||
SENDGRID_EMAIL
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
This app is **required** for Workflows
|
||||
</Note>
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "Stripe"
|
||||
---
|
||||
### Setting up Stripe
|
||||
|
||||
<Steps>
|
||||
<Step title="Create or log into a Stripe account">
|
||||
Go to Stripe and either create a new account or log into an existing one. For testing, activate the Test-Mode toggle in the top right of the Stripe dashboard.
|
||||
</Step>
|
||||
<Step title="Save API keys">
|
||||
Open [Stripe API Keys](https://dashboard.stripe.com/apikeys), then save the token starting with `pk_...` to `NEXT_PUBLIC_STRIPE_PUBLIC_KEY` and `sk_...` to `STRIPE_PRIVATE_KEY` in the `.env` file.
|
||||
</Step>
|
||||
<Step title="Activate OAuth for Standard Accounts">
|
||||
Go to [Stripe Connect Settings](https://dashboard.stripe.com/settings/connect) and activate OAuth for Standard Accounts.
|
||||
</Step>
|
||||
<Step title="Add the redirect URL">
|
||||
Add the following redirect URL, replacing `<Cal.com URL>` with your application's URL:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/stripepayment/callback
|
||||
```
|
||||
</Step>
|
||||
<Step title="Save the Stripe Client ID">
|
||||
Copy your client ID (`ca_...`) to `STRIPE_CLIENT_ID` in the `.env` file.
|
||||
</Step>
|
||||
<Step title="Set up a Stripe webhook">
|
||||
Open [Stripe Webhooks](https://dashboard.stripe.com/webhooks) and add:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/stripepayment/webhook
|
||||
```
|
||||
as the webhook for connected applications.
|
||||
</Step>
|
||||
<Step title="Select webhook events">
|
||||
Select all `payment_intent` events for the webhook.
|
||||
</Step>
|
||||
<Step title="Save the webhook secret">
|
||||
Copy the webhook secret (`whsec_...`) to `STRIPE_WEBHOOK_SECRET` in the `.env` file.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: "Twilio"
|
||||
---
|
||||
<Steps>
|
||||
<Step title="Create a Twilio account">
|
||||
Go to [Twilio](https://www.twilio.com/try-twilio) and create a new account.
|
||||
</Step>
|
||||
<Step title="Get a Twilio phone number">
|
||||
Click on 'Get a Twilio phone number' to obtain a phone number for your account.
|
||||
</Step>
|
||||
<Step title="Save the Account SID">
|
||||
Copy the Account SID and add it to your `.env` file under the field:
|
||||
```
|
||||
TWILIO_SID
|
||||
```
|
||||
</Step>
|
||||
<Step title="Save the Auth Token">
|
||||
Copy the Auth Token and add it to your `.env` file under the field:
|
||||
```
|
||||
TWILIO_TOKEN
|
||||
```
|
||||
</Step>
|
||||
<Step title="Save the Twilio phone number">
|
||||
Copy your Twilio phone number and add it to your `.env` file under the field:
|
||||
```
|
||||
TWILIO_PHONE_NUMBER
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set the Sender ID">
|
||||
Add your own sender ID to the `.env` file under the field:
|
||||
```
|
||||
NEXT_PUBLIC_SENDER_ID
|
||||
```
|
||||
(The fallback is set to "Cal" if not specified.)
|
||||
</Step>
|
||||
<Step title="Create a Messaging Service">
|
||||
Navigate to **Develop** -> **Messaging** -> **Services**, then create a new messaging service.
|
||||
</Step>
|
||||
<Step title="Name the Messaging Service">
|
||||
Choose a name for the messaging service. This can be anything you like.
|
||||
</Step>
|
||||
<Step title="Add Senders to the Messaging Service">
|
||||
Click 'Add Senders' and select 'Phone number' as the sender type.
|
||||
</Step>
|
||||
<Step title="Add your Twilio phone number as a sender">
|
||||
Add the listed phone number to the messaging service.
|
||||
</Step>
|
||||
<Step title="Complete the Messaging Service setup">
|
||||
Leave all other fields as they are, then complete the setup by clicking ‘View my new Messaging Service’.
|
||||
</Step>
|
||||
<Step title="Save the Messaging Service SID">
|
||||
Copy the Messaging Service SID and add it to your `.env` file under the field:
|
||||
```
|
||||
TWILIO_MESSAGING_SID
|
||||
```
|
||||
</Step>
|
||||
<Step title="Create a Verify Service">
|
||||
Go to the Twilio dashboard, create a new Verify Service, and name it as you wish.
|
||||
</Step>
|
||||
<Step title="Save the Verify Service SID">
|
||||
Copy the Verify Service SID and add it to your `.env` file under the field:
|
||||
```
|
||||
TWILIO_VERIFY_SID
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
This app is **required** for Workflows
|
||||
</Note>
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: "Zoho"
|
||||
---
|
||||
#### Obtaining ZohoCRM Client ID and Secret
|
||||
|
||||
<Steps>
|
||||
<Step title="Sign into Zoho API Console">
|
||||
Go to [Zoho API Console](https://api-console.zoho.com/) and sign into your account, or create a new one.
|
||||
</Step>
|
||||
<Step title="Go to Applications">
|
||||
From the API console page, navigate to "Applications".
|
||||
</Step>
|
||||
<Step title="Add a New Client">
|
||||
Click the "ADD CLIENT" button at the top right and select "Server-based Applications".
|
||||
</Step>
|
||||
<Step title="Fill in Client Details">
|
||||
Enter any desired information in the "Client Details" tab.
|
||||
</Step>
|
||||
<Step title="Go to the Client Secret tab">
|
||||
Navigate to the "Client Secret" tab.
|
||||
</Step>
|
||||
<Step title="Save Client ID and Secret to .env">
|
||||
Copy the Client ID and Client Secret into your `.env` file under:
|
||||
```
|
||||
ZOHOCRM_CLIENT_ID
|
||||
ZOHOCRM_CLIENT_SECRET
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set the Redirect URL for OAuth">
|
||||
Set the Redirect URL for OAuth to:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/zohocrm/callback
|
||||
```
|
||||
Replace `<Cal.com URL>` with your application URL.
|
||||
</Step>
|
||||
<Step title="Enable Multi-DC Option">
|
||||
In the "Settings" section, check the "Multi-DC" option if you wish to use the same OAuth credentials for all data centers.
|
||||
</Step>
|
||||
<Step title="Save your settings">
|
||||
Click "Save" or "UPDATE" at the bottom of the page.
|
||||
</Step>
|
||||
<Step title="Integration is Ready">
|
||||
Your ZohoCRM integration can now be easily added in the Cal.com settings.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
#### Obtaining Zoho Calendar Client ID and Secret
|
||||
|
||||
<Steps>
|
||||
<Step title="Sign into Zoho API Console">
|
||||
Go to [Zoho API Console](https://api-console.zoho.com/) and sign into your account, or create a new one.
|
||||
</Step>
|
||||
<Step title="Create a New Server-based Application">
|
||||
Choose "Server-based Applications" and set the Redirect URL for OAuth to:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/zohocalendar/callback
|
||||
```
|
||||
Replace `<Cal.com URL>` with your application URL.
|
||||
</Step>
|
||||
<Step title="Fill in Client Details">
|
||||
Enter any information you want in the "Client Details" tab.
|
||||
</Step>
|
||||
<Step title="Go to the Client Secret tab">
|
||||
Navigate to the "Client Secret" tab.
|
||||
</Step>
|
||||
<Step title="Save Credentials in Cal.com Admin Panel">
|
||||
Copy the Client ID and Client Secret to your app keys in the Cal.com admin panel at:
|
||||
```
|
||||
<Cal.com>/settings/admin/apps
|
||||
```
|
||||
</Step>
|
||||
<Step title="Enable Multi-DC Option">
|
||||
In the "Settings" section of Zoho API Console, check the "Multi-DC" option if you wish to use the same OAuth credentials across data centers.
|
||||
</Step>
|
||||
<Step title="Save Settings">
|
||||
Click "Save" or "UPDATE" at the bottom of the page.
|
||||
</Step>
|
||||
<Step title="Complete Zoho Calendar Integration">
|
||||
Your Zoho Calendar integration is now ready and can be managed at:
|
||||
```
|
||||
/settings/my-account/calendars
|
||||
```
|
||||
</Step>
|
||||
<Step title="Access Zoho Calendar">
|
||||
You can access your Zoho calendar at [https://calendar.zoho.com/](https://calendar.zoho.com/).
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
If you use multiple calendars with Cal, make sure to enable the toggle to prevent double-bookings across calendars. This setting can be found at `/settings/my-account/calendars`.
|
||||
</Note>
|
||||
|
||||
#### Obtaining Zoho Bigin Client ID and Secret
|
||||
|
||||
<Steps>
|
||||
<Step title="Sign into Zoho API Console">
|
||||
Go to [Zoho API Console](https://api-console.zoho.com/) and sign into your account, or create a new one.
|
||||
</Step>
|
||||
<Step title="Add a New Client for Zoho Bigin">
|
||||
Click the "ADD CLIENT" button at the top right, and select "Server-based Applications".
|
||||
</Step>
|
||||
<Step title="Set the Redirect URL for OAuth">
|
||||
Set the Redirect URL for OAuth to:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/zoho-bigin/callback
|
||||
```
|
||||
Replace `<Cal.com URL>` with your application URL.
|
||||
</Step>
|
||||
<Step title="Go to the Client Secret tab">
|
||||
Navigate to the "Client Secret" tab.
|
||||
</Step>
|
||||
<Step title="Save Client ID and Secret to .env.appStore">
|
||||
Copy the Client ID and Client Secret into the `.env.appStore` file under:
|
||||
```
|
||||
ZOHO_BIGIN_CLIENT_ID
|
||||
ZOHO_BIGIN_CLIENT_SECRET
|
||||
```
|
||||
</Step>
|
||||
<Step title="Enable Multi-DC Option">
|
||||
In the "Settings" section, check the "Multi-DC" option if you wish to use the same OAuth credentials across data centers.
|
||||
</Step>
|
||||
<Step title="Complete Zoho Bigin Integration">
|
||||
Your Zoho Bigin integration is now ready and can be added from the Cal.com app store.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "Zoom"
|
||||
---
|
||||
**Obtaining Zoom Client ID and Secret**
|
||||
|
||||
<Steps>
|
||||
<Step title="Sign into Zoom Marketplace">
|
||||
Go to [Zoom Marketplace](https://marketplace.zoom.us/) and sign in with your Zoom account.
|
||||
</Step>
|
||||
<Step title="Build a New App">
|
||||
In the upper right, click "Develop" and then "Build App".
|
||||
</Step>
|
||||
<Step title="Create an OAuth App">
|
||||
Under "OAuth", select "Create".
|
||||
</Step>
|
||||
<Step title="Name Your App">
|
||||
Provide a name for your app.
|
||||
</Step>
|
||||
<Step title="Choose User-managed App Type">
|
||||
Select "User-managed app" as the app type.
|
||||
</Step>
|
||||
<Step title="Set Marketplace Visibility">
|
||||
De-select the option to publish the app on the Zoom App Marketplace.
|
||||
</Step>
|
||||
<Step title="Create the App">
|
||||
Click "Create" to proceed.
|
||||
</Step>
|
||||
<Step title="Save Client ID and Secret">
|
||||
Copy the Client ID and Client Secret and add them to your `.env` file under the fields:
|
||||
```
|
||||
ZOOM_CLIENT_ID
|
||||
ZOOM_CLIENT_SECRET
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set the Redirect URL for OAuth">
|
||||
Set the Redirect URL for OAuth to:
|
||||
```
|
||||
<Cal.com URL>/api/integrations/zoomvideo/callback
|
||||
```
|
||||
Replace `<Cal.com URL>` with your application URL.
|
||||
</Step>
|
||||
<Step title="Configure Allow List and Subdomain Check">
|
||||
Add the redirect URL to the allow list and enable "Subdomain check". Ensure it displays "saved" below the form.
|
||||
</Step>
|
||||
<Step title="Skip Basic Information and Add Scopes">
|
||||
You don't need to provide basic information about your app. Instead, go to "Scopes", click "+ Add Scopes", then select the category "Meeting" on the left, and check the scope `meeting:write`.
|
||||
</Step>
|
||||
<Step title="Save the Scope">
|
||||
Click "Done" to save the scope settings.
|
||||
</Step>
|
||||
<Step title="Complete Zoom Integration">
|
||||
Your Zoom integration is now ready and can be easily added in the Cal.com settings.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "Database migrations"
|
||||
icon: "upload"
|
||||
---
|
||||
|
||||
As described in the [upgrade guide](/self-hosting/upgrading), you should use the
|
||||
```
|
||||
yarn workspace @calcom/prisma db-migrate
|
||||
```
|
||||
or
|
||||
```
|
||||
yarn workspace @calcom/prisma db-deploy
|
||||
```
|
||||
command to update the database.
|
||||
|
||||
We use database migrations in order to handle changes to the database schema in a more secure and stable way. This is actually very common. The thing is that when just changing the schema in `schema.prisma` without creating migrations, the update to the newer database schema can damage or delete all data in production mode, since the system sometimes doesn't know how to transform the data from A to B. Using migrations, each step is reproducable, transparent and can be undone in a simple way.
|
||||
|
||||
### Creating migrations
|
||||
|
||||
If you are modifying the codebase and make a change to the `schema.prisma` file, you must create a migration.
|
||||
|
||||
To create a migration for your previously changed `schema.prisma`, simply run the following:
|
||||
|
||||
```
|
||||
yarn workspace @calcom/prisma db-migrate
|
||||
```
|
||||
|
||||
Now, you must create a short name for your migration to describe what changed (for example, "user_add_email_verified"). Then just add and commit it with the corresponding code that uses your new database schema.
|
||||
|
||||
<Warning>
|
||||
Always keep an eye on what migrations Prisma is generating.** Prisma often happily will drop entire columns of data because it can't figure out what to do.
|
||||
</Warning>
|
||||
|
||||
### Error: The database schema is not empty
|
||||
|
||||
Prisma uses a database called `_prisma_migrations` to keep track of which migrations have been applied and which haven't. If your local migrations database doesn't match up with what's in the actual database, then Prisma will throw the following error:
|
||||
|
||||
```
|
||||
Error: P3005
|
||||
|
||||
The database schema for `localhost:5432` is not empty. Read more about how to baseline an existing production database: https://pris.ly/d/migrate-baseline
|
||||
```
|
||||
|
||||
In order to fix this, we need to tell Prisma which migrations have already been applied.
|
||||
|
||||
This can be done by running the following command, replacing `migration_name` with each migration that you have already applied:
|
||||
|
||||
```
|
||||
yarn prisma migrate resolve --applied migration_name
|
||||
```
|
||||
|
||||
You will need to run the command for each migration that you want to mark as applied.
|
||||
|
||||
### Resetting Prisma migrate
|
||||
|
||||
When your local Prisma database runs out of sync with migrations on local and you are tearing your hair out, I’ve been there, so you don’t have to:
|
||||
|
||||
**PostgreSQL**
|
||||
|
||||
```
|
||||
DELETE FROM "_prisma_migrations";
|
||||
```
|
||||
|
||||
**Quickly re-index**
|
||||
|
||||
```
|
||||
# Run the following to easily apply all migrations in the prisma/migrations directory
|
||||
ls -1a prisma/migrations/ | grep 2021 | xargs -I{} prisma migrate resolve --applied {}
|
||||
```
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: "AWS"
|
||||
icon: "aws"
|
||||
---
|
||||
|
||||
Deploying Cal.com on AWS
|
||||
___
|
||||
|
||||
<Steps>
|
||||
<Step title="Prerequisites">
|
||||
1. Amazon Web Services account
|
||||
2. Familiarity with AWS services and management console
|
||||
3. Access to the Cal.com source code
|
||||
</Step>
|
||||
<Step title="AWS Environment Setup">
|
||||
1. Create an AWS Account: If not already set up, create an account on AWS.
|
||||
2. Management Console: Log in to the AWS Management Console.
|
||||
</Step>
|
||||
<Step title="Creating AWS Resources">
|
||||
1. Create a New IAM User: Set up an IAM user with the necessary permissions for deploying and managing the application.
|
||||
2. Set Up Required Services: Establish services like Amazon EC2, RDS for PostgreSQL, etc., as needed for your application.
|
||||
</Step>
|
||||
<Step title="Configuring Cal.com">
|
||||
1. Clone the Repository: Get the Cal.com repository onto your local environment.
|
||||
2. Update Configuration: Modify the .env file to include your AWS resource details (like database endpoints).
|
||||
</Step>
|
||||
<Step title="Deploying on AWS">
|
||||
1. Deploy Application: Utilize AWS services such as EC2 or Elastic Beanstalk to deploy the Cal.com application.
|
||||
2. Database Configuration: Set up and connect the RDS instance to your application.
|
||||
3. Verify Deployment: Ensure the application is operational and accessible.
|
||||
</Step>
|
||||
<Step title="Post-Deployment Steps">
|
||||
1. DNS Setup: Update your DNS settings to point to your AWS deployment.
|
||||
2. Monitoring and Scaling: Leverage AWS monitoring tools to keep track of your application's performance and scale resources accordingly.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. Adhere to AWS's recommended security practices.
|
||||
2. Regularly update your deployment with the latest Cal.com releases.
|
||||
|
||||
|
||||
### Additional Resources
|
||||
|
||||
https://docs.aws.amazon.com/
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Azure"
|
||||
icon: "microsoft"
|
||||
---
|
||||
|
||||
Deploying Cal.com on Azure
|
||||
___
|
||||
|
||||
<Steps>
|
||||
<Step title="Prerequisites">
|
||||
1. Microsoft Azure account
|
||||
2. Basic knowledge of Azure services
|
||||
3. Access to Cal.com source code
|
||||
</Step>
|
||||
<Step title="Azure Setup">
|
||||
1. Create an Azure Account
|
||||
2. Azure Portal: Familiarize yourself with the Azure Portal.
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/142919730/65404c14-a70c-4a10-a253-f4cd4a7de421" />
|
||||
</Step>
|
||||
<Step title="Creating Azure Resources">
|
||||
1. Creating Azure Resources: In the Azure Portal, create a new resource group for your Cal.com project.
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/142919730/ac301959-9280-40ce-a8f9-061ea18f287a" />
|
||||
2. Create Azure Services: Set up required services such as Azure App Service, Azure Database for PostgreSQL, etc.
|
||||
#### Create Web App
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/142919730/3ce2984a-bca2-486f-a675-ac5fd719efd2" />
|
||||
|
||||
#### Setup Database, Networking
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/142919730/9eefd029-1b8f-4163-b35c-fa34dd8e4eb4" />
|
||||
|
||||
#### Setup Monitoring
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/142919730/49ed309c-c70d-486e-84be-37ea1e8ca14e" />
|
||||
</Step>
|
||||
<Step title="Configuring Cal.com">
|
||||
1. Clone Repository: Clone the Cal.com repository to your local machine.
|
||||
2. Configuration Files: Update the .env file with necessary Azure configurations (e.g., database connection strings).
|
||||
</Step>
|
||||
<Step title="Deploying on Azure">
|
||||
1. Deploying Web App: Use Azure App Service to deploy the Cal.com web application.
|
||||
2. Database Setup: Deploy and configure the Azure Database for PostgreSQL with Cal.com.
|
||||
3. Deployment Verification: Ensure that the application is running smoothly post-deployment.
|
||||
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/142919730/8ca084e4-eb4e-4ff5-8445-caf002eed500" />
|
||||
</Step>
|
||||
<Step title="Post-Deployment Steps">
|
||||
1. DNS Configuration: Configure your DNS settings to point to the Azure deployment.
|
||||
2. Monitor and Scale: Utilize Azure monitoring tools to keep track of performance and scale resources as needed.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: "GCP"
|
||||
icon: "google"
|
||||
---
|
||||
|
||||
Deploying Cal.com on Google Cloud Platform (GCP)
|
||||
|
||||
In this guide, we will go over the steps to deploy cal.com on Google Cloud Platform (GCP). We will cover how to create a virtual machine, configure it, install Docker, and finally deploy the cal.com application.
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating a Virtual Machine">
|
||||
### Go to the GCP Console
|
||||
|
||||
First, open the Google Cloud Platform console by visiting the [https://console.cloud.google.com/](https://console.cloud.google.com/) website.
|
||||
|
||||
### Create a New Project
|
||||
|
||||
If you haven't already, create a new project by clicking on the "Select a project" dropdown menu and selecting "New Project". Enter a name for your project and click on the "Create" button.
|
||||
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/30791239/949881fb-c659-4952-9c51-1d956a19cc36"/>
|
||||
|
||||
|
||||
### Create a New VM Instance
|
||||
|
||||
Click on the navigation menu icon (three horizontal lines) and select "Compute Engine" from the list. Then, click on "VM instances" in the sub-menu.
|
||||
|
||||
Click on the "Create" button to create a new virtual machine.
|
||||
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/30791239/bfa28fb3-a08e-4dd8-867a-1951ca11e0f2" />
|
||||
|
||||
|
||||
### Select the Machine Type
|
||||
|
||||
Choose the machine type that best suits your needs. Ideally, 2 vCPUs and 2-4GB RAM is enough.
|
||||
|
||||
### Set Up Networking
|
||||
|
||||
Make sure the "Networking" tab is selected and click on the "Add network" button. Choose the "Default" network and click on the "Add" button.
|
||||
|
||||
|
||||
### Create the Instance
|
||||
|
||||
Review the details of your virtual machine and click on the "Create" button to create the instance.
|
||||
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/30791239/05e34917-8be4-4d72-8bcf-aff8cbf537c3" />
|
||||
Note the public IP of the VM.
|
||||
</Step>
|
||||
<Step title="Configuring the Virtual Machine">
|
||||
Once your virtual machine is created, you need to configure it to allow traffic on port 80.
|
||||
|
||||
### Open Port 80
|
||||
|
||||
Click on the navigation menu icon (three horizontal lines) and select "Compute Engine" from the list. Then, click on "VM instances" in the sub-menu. Find your newly created instance and click on its name to enter its details page.
|
||||
|
||||
Click on the "Firewalls" tab and then click on the "Add firewall rule" button. Select "Allow all" as the source and destination, set the protocol to "tcp" and the ports to "80". Click on the "Add" button to save the changes.
|
||||
</Step>
|
||||
<Step title="Installing Docker">
|
||||
Now that your virtual machine is configured, you need to install Docker on it.
|
||||
|
||||
### Connect to Your Instance
|
||||
|
||||
Open a terminal window on your local machine and use SSH to connect to your virtual machine. You can find the external IP address or DNS name of your instance in the GCP console. Use the following command to connect to your instance:
|
||||
```bash
|
||||
gcloud ssh --project=[PROJECT_ID] --zone=[ZONE] [INSTANCE_NAME]
|
||||
```
|
||||
Replace `[PROJECT_ID]` with your project ID, `[ZONE]` with the zone where your instance is located, and `[INSTANCE_NAME]` with the name of your instance.
|
||||
You can also use web based SSH.
|
||||
|
||||
<img src="https://github.com/sriyachalla/cal.com/assets/30791239/89577c7e-0de6-4b31-b235-fcb33ed70de9" />
|
||||
|
||||
|
||||
### Install Docker
|
||||
|
||||
Once connected, update the package list and install Docker using the following commands:
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install docker.io
|
||||
```
|
||||
### Start the Docker Service
|
||||
|
||||
Start the Docker service using the following command:
|
||||
```bash
|
||||
sudo systemctl start docker
|
||||
```
|
||||
</Step>
|
||||
<Step title="Deploying Cal.com">
|
||||
Now that Docker is installed and running, you can deploy cal.com on your virtual machine.
|
||||
|
||||
### Pull the Docker Image
|
||||
|
||||
Use the following command to pull the cal.com Docker image from Docker Hub:
|
||||
```bash
|
||||
docker pull cal/calcom
|
||||
```
|
||||
### Run the Docker Container
|
||||
|
||||
Run the Docker container using the following command:
|
||||
```bash
|
||||
docker run -d -p 80:80 cal/cal.com
|
||||
```
|
||||
This command maps port 80 on your local machine to port 80 inside the container, so you can access cal.com from outside the container.
|
||||
|
||||
### Access Cal.com
|
||||
|
||||
Open a web browser and navigate to `http://localhost`. You should now be able to access the cal.com homepage.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Congratulations! You have successfully deployed cal.com on Google Cloud Platform.
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: "Vercel"
|
||||
icon: "triangle"
|
||||
iconType: "solid"
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
You need a PostgresDB database hosted somewhere. [Supabase](https://supabase.com/) offer a great free option while [Heroku](https://www.heroku.com/) offers a low-cost option.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Local settings
|
||||
|
||||
<Steps>
|
||||
<Step title="Fork and clone the repository">
|
||||
```
|
||||
git clone https://github.com/\<your-fork\>/cal.com.git
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set environment variables">
|
||||
Copy the `.env.example` file in `apps/web`, rename it to `.env` and fill it with your settings ([See manual setup](https://github.com/calcom/cal.com#manual-setup) and [Obtaining the Google API Credentials](https://github.com/calcom/cal.com#obtaining-the-google-api-credentials))
|
||||
</Step>
|
||||
<Step title="Install packages with yarn">
|
||||
```
|
||||
yarn install
|
||||
```
|
||||
</Step>
|
||||
<Step title="Set up the database using the Prisma schema">
|
||||
Schema is located in at `packages/prisma/schema.prisma`.
|
||||
|
||||
```
|
||||
yarn workspace @calcom/prisma db-deploy
|
||||
```
|
||||
</Step>
|
||||
<Step title="Open [Prisma Studio](https://www.prisma.io/studio)">
|
||||
To look at or modify the database content
|
||||
```
|
||||
yarn db-studio
|
||||
```
|
||||
</Step>
|
||||
<Step title="Open User model">
|
||||
Click on the `User` model to add a new user record.
|
||||
</Step>
|
||||
<Step title="Create new user">
|
||||
Fill out the fields (remembering to encrypt your password with [BCrypt](https://bcrypt-generator.com/)) and click `Save 1 Record` to create your first user.
|
||||
</Step>
|
||||
<Step title="Login">
|
||||
Open a browser to [port 3000](http://localhost:3000/) on your localhost and login with your just created, first user.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Sometimes, yarn install might fail during deployment on Vercel, in which case, you can use ```YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install``` as the install command instead.
|
||||
</Warning>
|
||||
|
||||
#### Deployment
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a new project on Vercel">
|
||||
</Step>
|
||||
<Step title="Import from your forked repository">
|
||||
</Step>
|
||||
<Step title="Set the Environment Variables">
|
||||
</Step>
|
||||
<Step title="Set the root directory to `apps/web`">
|
||||
</Step>
|
||||
<Step title="Override the build command">
|
||||
Override to:
|
||||
```
|
||||
cd ../.. && yarn build --include-dependencies --no-deps
|
||||
```
|
||||
</Step>
|
||||
<Step title="Hit Deploy">
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: "Docker"
|
||||
icon: "docker"
|
||||
---
|
||||
|
||||
The Docker configuration for Cal is an effort powered by people within the community. Cal.com, Inc. does not provide official support for Docker, but we will accept fixes and documentation. Use at your own risk.
|
||||
|
||||
If you want to contribute to the Docker repository, [reply here](https://github.com/calcom/docker/discussions/32).
|
||||
|
||||
The Docker configuration can be found [in our docker repository](https://github.com/calcom/docker).
|
||||
|
||||
### Requirements
|
||||
|
||||
Make sure you have `docker` & `docker compose` installed on the server / system.
|
||||
|
||||
Note: `docker compose` without the hyphen is now the primary method of using docker-compose, per the Docker documentation.
|
||||
|
||||
### Getting Started
|
||||
|
||||
1. Clone calcom-docker
|
||||
|
||||
```
|
||||
git clone --recursive https://github.com/calcom/docker.git calcom-docker
|
||||
```
|
||||
|
||||
2. Change into the directory
|
||||
|
||||
```
|
||||
cd calcom-docker
|
||||
```
|
||||
|
||||
3. Update the calcom submodule
|
||||
|
||||
```
|
||||
git submodule update --remote --init
|
||||
```
|
||||
|
||||
4. Rename `.env.example` to `.env` and then update `.env`
|
||||
|
||||
5. Build and start Cal.com via docker compose
|
||||
|
||||
```
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
6. (First Run) Open a browser to [http://localhost:5555](http://localhost:5555/) to look at or modify the database content.
|
||||
|
||||
a. Click on the `User` model to add a new user record.
|
||||
|
||||
b. Fill out the fields (remembering to encrypt your password with [BCrypt](https://bcrypt-generator.com/)) and click `Save 1 Record` to create your first user.
|
||||
|
||||
7. Open a browser to [http://localhost:3000](http://localhost:3000/) and login with your just created, first user.
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Build-time variables
|
||||
|
||||
These variables must be provided at the time of the docker build, and can be provided by updating the .env file. Changing these is not required for evaluation, but may be required for running in production. Currently, if you require changes to these variables, you must follow the instructions to build and publish your own image.
|
||||
|
||||
* NEXT_PUBLIC_WEBAPP_URL
|
||||
|
||||
* NEXT_PUBLIC_LICENSE_CONSENT
|
||||
|
||||
* NEXT_PUBLIC_TELEMETRY_KEY
|
||||
|
||||
#### Important Run-time variables
|
||||
|
||||
* NEXTAUTH_SECRET
|
||||
|
||||
### Git Submodules
|
||||
|
||||
This repository uses a git submodule.
|
||||
|
||||
To update the calcom submodule, use the following command:
|
||||
|
||||
```
|
||||
git submodule update --remote --init
|
||||
```
|
||||
|
||||
For more advanced usage, please refer to the git documentation: [https://git-scm.com/book/en/v2/Git-Tools-Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
* SSL edge termination: If running behind a load balancer which handles SSL certificates, you will need to add the environmental variable `NODE_TLS_REJECT_UNAUTHORIZED=0` to prevent requests from being rejected. Only do this if you know what you are doing and trust the services/load-balancers directing traffic to your service.
|
||||
|
||||
* Failed to commit changes: Invalid 'prisma.user.create()': Certain versions may have trouble creating a user if the field `metadata` is empty. Using an empty json object `{}` as the field value should resolve this issue. Also, the `id` field will autoincrement, so you may also try leaving the value of `id` as empty.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: "How to sync third party apps"
|
||||
---
|
||||
|
||||
<Steps>
|
||||
<Step title="Add the required variables in your `.env` file">
|
||||
1. `CALCOM_WEBHOOK_SECRET`
|
||||
- You can generate this by running `openssl rand -base64 32`. This is required when sending 3rd party app credentials from your platform to your instance of Cal.com.
|
||||
2. On your self-hosted instance of Cal.com visit settings/admin/apps under an admin account. Here you can enable/disable apps on Cal.com and set the app keys (client id, client secret, etc.). These keys should match the ones on your platform.
|
||||
3. `CALCOM_WEBHOOK_HEADER_NAME`
|
||||
- The header name is expected to contain the webhook secret. The default is `calcom-webhook-secret`
|
||||
5. `CALCOM_CREDENTIAL_SYNC_ENDPOINT`
|
||||
- The endpoint on your platform that your instance of [Cal.com](http://Cal.com) will make a request to if the 3rd party app credentials are expired.
|
||||
5. `CALCOM_APP_CREDENTIAL_ENCRYPTION_KEY`
|
||||
- When sending 3rd party app credentials between your platform and your instance Cal.com, we expect these to be encrypted using AES256. When you encrypt the 3rd party app credentials, ensure the same key is used.
|
||||
|
||||
</Step>
|
||||
<Step title="Sending credentials to your cal.com instance">
|
||||
When a user adds a 3rd party app on your platform, you should send the credentials that are created to your instance of [Cal.com](http://Cal.com) to `${CALCOM_WEBAPP_URL}/api/webhook/app-credential` . The payload should contain the following
|
||||
|
||||
```javascript
|
||||
{
|
||||
// UserId of the Cal.com user
|
||||
userId: number;
|
||||
|
||||
// The app slug that is on Cal.com.
|
||||
// Can be found in the Cal.com database in the App table
|
||||
appSlug: string;
|
||||
|
||||
// The credentials from the 3rd party app. (ex. Access token, refresh token).
|
||||
// Ideally it should contain the access token and expiry date
|
||||
// AES256 encrypted with CALCOM_APP_CREDENTIAL_ENCRYPTION_KEY
|
||||
keys: string;
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Refreshing credentials">
|
||||
When [Cal.com](http://Cal.com) needs to refresh the app credentials it will make a request to `CALCOM_CREDENTIAL_SYNC_ENDPOINT`. The request contains the following.
|
||||
|
||||
```javascript
|
||||
{
|
||||
calcomUserId: string;
|
||||
// App slug on Cal.com
|
||||
appSlug: string;
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
|
||||
<Note>
|
||||
This only works if you have integrated [Cal.com](http://cal.com/) into your platform. Users **must** consent to give access to your platform, and you are simply using [Cal.com](http://cal.com/)'s code within your platform.
|
||||
</Note>
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "Can Cal.com sponsor my open source project?"
|
||||
---
|
||||
|
||||
Cal.com is a commercial open source company and thereby we fully support other open source projects, whether it's commercial or non-commercial. We're friends of many other COSS companies.
|
||||
|
||||
## Sponsorship Criteria
|
||||
|
||||
- The project should be non-commercial or a commercial open source company with less than $2M in ARR
|
||||
- The project should be open source
|
||||
- Include our "Book us with Cal.com" banner in your footer and link to a Cal.com booking link of your choice
|
||||
- Include our "Book us with Cal.com" banner in your open source repository's README.md file and link to a Cal.com booking link of your choice
|
||||
- Add the UTM tag with the format for the banners: ?utm_source=banner&utm_campaign=oss
|
||||
|
||||
|
||||
or
|
||||
|
||||
|
||||
### HTML Code:
|
||||
|
||||
```html
|
||||
<img alt="Book us with Cal.com" src="https://cal.com/book-with-cal-dark.svg" />
|
||||
```
|
||||
or
|
||||
```html
|
||||
<img alt="Book us with Cal.com" src="https://cal.com/book-with-cal-light.svg" />
|
||||
```
|
||||
|
||||
## How to apply
|
||||
|
||||
Please note that we have a limited number of openings for OSS sponsorships each month. If you're interested in applying for a sponsorship for your open source software project, please follow these steps:
|
||||
|
||||
- Ensure that you meet all the sponsorship criteria mentioned above.
|
||||
- Send an email to peer@cal.com and explain what you are working on and confirm that you meet all the sponsorship criteria (watch out, Peer may invest a small angel check in your COSS company 👀)
|
||||
- Explaining why Cal.com's free tier or open core is insufficient for your project
|
||||
- Include your Cal.com team slug and provide a link to your open source repository in the email.
|
||||
|
||||
<Note>
|
||||
Please note that sponsorship requests are reviewed on a monthly basis, so allow some time before reaching out for updates. We reserve the right to reject any project at will without reason.
|
||||
</Note>
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: "How to add custom CSS"
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Adding or modifying CSS counts as changing the code, so as per [our license](https://github.com/calcom/cal.com/blob/main/LICENSE) **you must either open-source your modified version or purchase an enterprise license.**
|
||||
</Warning>
|
||||
|
||||
Cal.com uses [TailwindCSS](https://tailwindcss.com/) as a replacement for traditional CSS styling within the application, but some people prefer to add CSS styles themselves.
|
||||
|
||||
CSS files should be stored in the `styles` directory within the codebase.
|
||||
|
||||
Within the `styles` directory, you will find two CSS files, `fonts.css` and `global.css`. We suggest not to add to these files, and instead create new CSS files and import them into the application. This helps reduce conflicts when pulling in changes that we've made to either of the existing CSS files.
|
||||
|
||||
### Adding new stylesheets
|
||||
|
||||
Firstly, create the CSS file inside the `styles` directory.
|
||||
|
||||
Then, open the `pages/_app.tsx` file, and you will see the following two lines:
|
||||
|
||||
```js
|
||||
import "../styles/fonts.css";
|
||||
import "../styles/globals.css";
|
||||
```
|
||||
|
||||
Duplicate one of these import statements and change the path to link to your new CSS stylesheet, like so:
|
||||
|
||||
```js
|
||||
import "../styles/your-new-stylesheet.css";
|
||||
```
|
||||
|
||||
<Info>
|
||||
These styles will apply to all pages and components in your application.
|
||||
</Info>
|
||||
|
||||
Due to the global nature of stylesheets, and to avoid conflicts, you may **only import them inside** **`pages/_app.tsx`**.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "How to white label the self hosted instance"
|
||||
---
|
||||
|
||||
If you're on the Ultimate or Platform plan of Cal.com, we have made it very easy for you to white label your self-hosted instance.
|
||||
|
||||
<Steps>
|
||||
<Step title="Update environment variables">
|
||||
Please update the following env variables to match your desired branding:
|
||||
```
|
||||
NEXT_PUBLIC_APP_NAME="acme.com"
|
||||
NEXT_PUBLIC_SUPPORT_MAIL_ADDRESS="support@acme.com"
|
||||
NEXT_PUBLIC_COMPANY_NAME="ACME inc."
|
||||
```
|
||||
</Step>
|
||||
<Step title="Update logos">
|
||||
The images for the logo are placed in `/web/public` . You can update the logo by changing the value of the following constants in `/packages/lib/constants.ts` file:
|
||||
1. LOGO
|
||||
2. LOGO_ICON
|
||||
to the file name of your logo and logo icon, or the paths with file name to your respective logo and logo icon images from `/web/public`.
|
||||
</Step>
|
||||
<Step title="Instance wide theming">
|
||||
The instance wide theme can be easily updated thanks to the color tokens we have in place. Simply modify the hex-codes within the `apps/web/styles/globals.css` file against the [color tokens](https://cal.com/docs/enterprise-features/instance-wide-theming), and the entire application can be consistently whitelabeled to your brand identity.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
If you're using custom SMTP server for emails, you might need to set `NODE_EXTRA_CA_CERTS` env variable equal to the path of your CA certificate so that it can be recognized by the calcom application.
|
||||
</Note>
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: "Installation"
|
||||
icon: "play"
|
||||
---
|
||||
|
||||
There are multiple ways in which you can deploy Cal.com, providing support for customers who want to implement Cal.com within their existing infrastructure stack. Let's go through them one-by-one. You can find the instructions for deployment in our README file, which is the section you see when you scroll down in our GitHub repository, or if you've got a copy of Cal.com downloaded already, you can open the file contained in the downloaded repository called `README.md`.
|
||||
|
||||
## Requirements
|
||||
|
||||
Cal.com runs with pretty minimal hardware requirements by itself. The most intensive part for the software is when you actually build the software, but once it's running it's relatively lightweight.
|
||||
|
||||
Cal.com works with a very large range of operating systems, as it only requires JavaScript execution to run. **Cal.com is known to work well with Windows, Mac, Linux and BSD.** Although they do work well on all of them, for production deployments we would suggest Linux as the ideal platform. Any operating system that runs Node.js should be able to work too, but these are some of the common operating systems that we know work well.
|
||||
|
||||
To run Cal.com, you need to install a few things. **Node.js, yarn, Git and PostgreSQL**. We use **Prisma** for database maintenance, and is one of the dependencies. We won’t publish installation guides for these as they have their own resources available on the internet. If you're on Linux/BSD, all of these things should be readily available on your package manager. Your best bet is searching for something like **Debian 12 PostgreSQL**, which will give you a guide to installing and configuring PostgreSQL on Debian Linux 12.
|
||||
|
||||
<Info>
|
||||
To ensure optimal performance and compatibility, we highly recommend using Node.js version 18 for your development environment. This version provides the best balance of stability, features, and security for this project. Please make sure to update your Node.js installation if necessary.
|
||||
</Info>
|
||||
|
||||
## Prisma Data Proxy
|
||||
|
||||
To use cal.com with prisma data proxy, you can:
|
||||
1. Set in the .env file
|
||||
```
|
||||
PRISMA_GENERATE_DATAPROXY=true
|
||||
```
|
||||
2. Set DATABASE_URL in the .env file equal to the prisma connection string
|
||||
```
|
||||
DATABASE_URL="prisma://****:****@****"
|
||||
```
|
||||
|
||||
## Production Build
|
||||
|
||||
1. First, you git clone the repository with the following command, so you have a copy of the code.
|
||||
```
|
||||
git clone https://github.com/calcom/cal.com.git
|
||||
```
|
||||
|
||||
<Note>
|
||||
If you are on windows, you would need to use the following command when cloning, with **admin privileges**:
|
||||
```
|
||||
git clone -c core.symlinks=true https://github.com/calcom/cal.com.git
|
||||
```
|
||||
</Note>
|
||||
|
||||
2. Then, go into the directory you just cloned with
|
||||
```
|
||||
cd cal.com
|
||||
```
|
||||
and run
|
||||
```
|
||||
yarn
|
||||
```
|
||||
to install all of the dependencies. Essentially, dependencies are just things that Cal.com needs to install to be able to work.
|
||||
|
||||
3. Then, you just need to set up a couple of things. For that, we use a `.env` file. We just need to copy and paste the `.env.example` file and rename the copy to `.env`. Here you'll have a template with comments showing you the settings you need/might want to set.
|
||||
|
||||
<Info>
|
||||
For preview deployments on **Vercel**, please leave the following environment variables empty:
|
||||
- **NEXTAUTH_URL**
|
||||
- **NEXT_PUBLIC_WEBSITE_URL**
|
||||
- **NEXT_PUBLIC_WEBAPP_URL**
|
||||
</Info>
|
||||
|
||||
4. Next, use the command
|
||||
```
|
||||
openssl rand -base64 32
|
||||
```
|
||||
(or another secret generator tool if you prefer) to generate a key and add it under `NEXTAUTH_SECRET` in the .env file.
|
||||
|
||||
5. You'll also want to fill out the `.env.appStore` file similar to the `.env` file as this includes keys to enable apps.
|
||||
|
||||
#### Production Build
|
||||
|
||||
For a production build, **please make sure** to set up [E2E testing](/developing/local-development#e2e-testing) and [Upgrading](/self-hosting/upgrading) the database from earlier version, and the proceed to build as follows:
|
||||
|
||||
```
|
||||
yarn build
|
||||
yarn start
|
||||
```
|
||||
|
||||
<Warning> Please make sure to upgrade your database before you build for production </Warning>
|
||||
|
||||
## Cron Jobs
|
||||
|
||||
There are a few features which require cron job setup. When self-hosting, you would probably need to set up cron jobs according to the hosting platform you are using.
|
||||
For instance, if you are hosting on Vercel, you would need to set up cron jobs by following [this document](https://vercel.com/guides/how-to-setup-cron-jobs-on-vercel).
|
||||
|
||||
At cal.com, the cron jobs are found in the following directory:
|
||||
```
|
||||
/apps/web/pages/api/cron
|
||||
```
|
||||
|
||||
|
||||
## App store seeder
|
||||
|
||||
<Info>
|
||||
We recommend using the admin UI/wizard instead of the seeder to enable app store apps
|
||||
</Info>
|
||||
|
||||
|
||||
## API
|
||||
|
||||
#### Step 1
|
||||
|
||||
Copy the .env files from their respective example files:
|
||||
|
||||
```
|
||||
cp apps/api/.env.example apps/api/V2/.env
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
#### Step 2
|
||||
|
||||
Install packages with yarn:
|
||||
|
||||
```
|
||||
yarn
|
||||
```
|
||||
|
||||
### Running API server
|
||||
|
||||
Build & Run the API V2 with yarn:
|
||||
|
||||
```
|
||||
yarn workspace @calcom/api-v2 build
|
||||
yarn workspace @calcom/api-v2 start
|
||||
```
|
||||
|
||||
## Vercel
|
||||
|
||||
As Cal.com is written in Next.js, Vercel is the perfect platform to host this on (Vercel built Next.js). You can simply follow the [instructions provided by Vercel to get started](https://vercel.com/docs/concepts/get-started). All you do is fork your own version of the repository, click new on Vercel and select the repository. It'll pretty much do the rest for you. The one thing you will need to do is set the environment variables (the .env file). As you can't create a .env file on Vercel, you can go into the settings and manually add each variable. Use the .env.example file for reference as to what you should add. You can learn more about [setting environment variables on Vercel here](https://vercel.com/docs/concepts/projects/environment-variables).
|
||||
|
||||
## Other environments
|
||||
|
||||
Cal.com effectively is just a Next.js application, so any possible solution you find online pertaining to Next.js applications should work. One example is Netlify, which is pretty similar to Vercel. It says it supports Next.js, so you can deploy Cal.com on Netlify. Refer to Netlify's docs on Next.js projects for more info. Another example is on a self hosted instance people may want to configure complex reverse proxies, SSL gateways and all sorts of other stuff. We can't officially support every configuration, but for any edge case where you may want to deploy Cal.com with X, just refer to X's docs on Next.js applications and you should be fine.
|
||||
|
||||
That's it. Your new self hosted Cal.com instance should now be up and running.
|
||||
|
||||
<Card href="/self-hosting/deployments" title="Deployments" icon="rocket">
|
||||
For more details on specific deployment instructions for AWS, Azure, etc.
|
||||
</Card>
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: "SSO setup"
|
||||
icon: "user-shield"
|
||||
---
|
||||
|
||||
Cal.com supports both Security Assertion Markup Language (SAML) and OpenID Connect (OIDC), two of the industry's leading authentication protocols. We prioritize your ease of access and security by providing robust Single Sign-On (SSO) capabilities. Whether you're looking for the XML-based standard of SAML or the lightweight OIDC, our platform is equipped to integrate smoothly with your preferred identity provider, ensuring both convenience and security for your users.
|
||||
|
||||
<Warning>
|
||||
You need an Enterprise License to avail this when self-hosting
|
||||
</Warning>
|
||||
|
||||
### Setting up SAML login
|
||||
|
||||
1. Set SAML_DATABASE_URL to a Postgres database. Please use a different database than the main Cal instance since the migrations are separate for this database. For example `postgresql://postgres:@localhost:5450/cal-saml`. If you are using a self-signed certificate for Postgres then use the `sslmode=no-verify` query param in the database URL. For example `postgresql://postgres:@localhost:5450/cal-saml?sslmode=no-verify`.
|
||||
|
||||
2. Set SAML_ADMINS to a comma separated list of admin emails from where the SAML metadata can be uploaded and configured.
|
||||
|
||||
3. Create a SAML application with your Identity Provider (IdP) using the instructions here - [SAML Setup](/self-hosting/sso-setup#saml-registration-with-identity-providers)
|
||||
|
||||
4. Remember to configure access to the IdP SAML app for all your users (who need access to Cal).
|
||||
|
||||
5. You will need the XML metadata from your IdP later, so keep it accessible.
|
||||
|
||||
6. Log in to one of the admin accounts configured in SAML_ADMINS and then navigate to Settings -> Security.
|
||||
|
||||
7. You should see a SAML configuration section, copy and paste the XML metadata from step 5 and click on Save.
|
||||
|
||||
8. Your provisioned users can now log into Cal using SAML.
|
||||
|
||||
### SAML Registration with Identity Providers
|
||||
|
||||
This guide explains the settings you need to use to configure SAML with your Identity Provider. Once this is set up you should get an XML metadata file that should then be uploaded on your Cal.com self-hosted instance.
|
||||
|
||||
> **Note:** Please do not add a trailing slash at the end of the URLs. Create them exactly as shown below.
|
||||
|
||||
**Assertion consumer service URL / Single Sign-On URL / Destination URL:** https://\<url for your self-hosted instance\>/api/auth/saml/callback [Replace the placeholder with the URL for your self-hosted Cal instance]
|
||||
|
||||
**Entity ID / Identifier / Audience URI / Audience Restriction:** [https://saml.cal.com](https://saml.cal.com)
|
||||
|
||||
**Response:** Signed
|
||||
|
||||
**Assertion Signature:** Signed
|
||||
|
||||
**Signature Algorithm:** RSA-SHA256
|
||||
|
||||
**Assertion Encryption:** Unencrypted
|
||||
|
||||
**Mapping Attributes / Attribute Statements:**
|
||||
|
||||
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier -> id
|
||||
|
||||
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress -> email
|
||||
|
||||
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname -> firstName
|
||||
|
||||
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname -> lastName
|
||||
|
||||
### Setting up OIDC login
|
||||
|
||||
1. Set SAML_DATABASE_URL to a Postgres database. Please use a different database than the main Cal instance since the migrations are separate for this database. For example `postgresql://postgres:@localhost:5450/cal-saml`. If you are using a self-signed certificate for Postgres then use the `sslmode=no-verify` query param in the database URL. For example `postgresql://postgres:@localhost:5450/cal-saml?sslmode=no-verify`.
|
||||
2. Set SAML_ADMINS to a comma separated list of admin emails who can configure the OIDC.
|
||||
3. Keep handy the Client Secret, Client ID and Well Known URL with you for the next step.
|
||||
4. Spin up cal.com on your server and login with the Admin user (the email ID of which was provided in step 2 for SAML_ADMINS environment variable).
|
||||
5. Visit `{BASE_URL}/settings/security/sso` and you should see something like this:
|
||||
<img src="./images/i1600x900-8ufcUyCOVwV6_hdudno.png" />
|
||||
6. Click on Configure SSO with OIDC, and then enter the Client Secret, Client ID and Well known URL from the Step 3, and click save.
|
||||
<img src="./images/i1600x900-GN1NLgrcf5r4_tmhni3.png" />
|
||||
7. That's it. Now when you try to login with SSO, your OIDC provider will handle the auth.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: "Upgrading"
|
||||
icon: "cloud-check"
|
||||
---
|
||||
|
||||
Pull the current version:
|
||||
|
||||
```
|
||||
git pull
|
||||
```
|
||||
|
||||
Check if dependencies got added/updated/removed
|
||||
|
||||
```
|
||||
yarn
|
||||
```
|
||||
|
||||
Apply database migrations by running **one of** the following commands:
|
||||
|
||||
In a development environment, run:
|
||||
|
||||
```
|
||||
yarn workspace @calcom/prisma db-migrate
|
||||
```
|
||||
|
||||
(this can clear your development database in some cases)
|
||||
|
||||
In a production environment, run:
|
||||
|
||||
```
|
||||
yarn workspace @calcom/prisma db-deploy
|
||||
```
|
||||
|
||||
Check for `.env` variables changes
|
||||
|
||||
```
|
||||
yarn predev
|
||||
```
|
||||
|
||||
Start the server. In a development environment, just do:
|
||||
|
||||
```
|
||||
yarn dev
|
||||
```
|
||||
|
||||
For a production build, run for example:
|
||||
|
||||
```
|
||||
yarn build
|
||||
yarn start
|
||||
```
|
||||
|
||||
Enjoy the new version.
|
||||
Reference in New Issue
Block a user