Skip to content

Commit dc290a6

Browse files
adityaoberaiadityaoberai
authored
Merge pull request #2005 from appwrite/add-project-v-docs
Add self-hosting docs for Sites
2 parents 7aa526b + e8f97b7 commit dc290a6

File tree

8 files changed

+286
-128
lines changed

8 files changed

+286
-128
lines changed

‎src/partials/configure-github-app.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Configure GitHub app {% #git %}
2+
3+
Appwrite supports automatic deployments through Git integration. In order for Appwrite to access your repos, you must [create a GitHub app](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) to enable this integration. The GitHub app requires the following configurations.
4+
5+
For automatic Git deployment to work, Appwrite needs to receive communication from GitHub, this means your Appwrite project must be accessible on the internet. If you're running on `localhost`, you need to run a proxy like [ngrok](https://ngrok.com/).
6+
7+
## GitHub App name {% #github-app-name %}
8+
9+
The GitHub App name will be displayed when connecting Appwrite to GitHub. In addition, this name will be transformed to a slug ("My GitHub App" will become "my-github-app") and appear in the URL when accessing your app in GitHub. This slug should be set as the `_APP_VCS_GITHUB_APP_NAME` environment variable in Appwrite.
10+
11+
## Homepage URL {% #github-homepage-url %}
12+
13+
The homepage URL will appear when looking at the public page of your app. It can be any URL you'd like.
14+
15+
## Callback URL {% #callback %}
16+
17+
GitHub will use **callback URLs** to redirect users back to Appwrite. Set these callback URLs under **Identifying and authorizing users** in the same order as listed below.
18+
19+
| URLs |
20+
| ----------------------------------------------------------------------------- |
21+
| `https://<HOSTNAME_OR_IP>/v1/vcs/github/callback` |
22+
| `https://<HOSTNAME_OR_IP>/v1/account/sessions/oauth2/callback/github/console` |
23+
24+
Also, check the **Request user authentication (OAuth) during installation** box.
25+
26+
## Post installation {% #post-install %}
27+
28+
Check the **Redirect on update** box under the **Post installation** section.
29+
30+
## Webhook {% #github-webhooks %}
31+
32+
GitHub will notify Appwrite about events like new commits using webhooks. Under **Webhook**, you need to check the **Active** checkbox. You also need to set the **Webhook URL** as `https://<HOSTNAME_OR_IP>/v1/vcs/github/events`.
33+
34+
If you're running Appwrite on `localhost`, GitHub can't send requests to Appwrite through webhooks and automatic deployments won't work. You'll need to host Appwrite on a server or use a proxy like [ngrok](https://ngrok.com/) to make Appwrite accessible to GitHub.
35+
36+
## Repository permissions {% #repository-permission %}
37+
38+
Configure these permissions under the **Repository permission** dropdown.
39+
40+
| Permission | Access |
41+
| --------------- | -------------- |
42+
| Administration | Read and write |
43+
| Checks | Read and write |
44+
| Commit Statuses | Read and write |
45+
| Contents | Read and write |
46+
| Issues | Read and write |
47+
| Metadata | Read-only |
48+
| Pull requests | Read and write |
49+
| Webhooks | Read and write |
50+
51+
## Account permissions {% #account-permission %}
52+
53+
Configure these permissions under the **Account Permission** dropdown.
54+
55+
| Permission | Access |
56+
| ------------- | --------- |
57+
| Email address | Read-only |
58+
59+
## Subscribe to events {% #subscribe-events %}
60+
61+
Select these under the **Subscribe to events** dropdown.
62+
63+
| Events |
64+
| ------------ |
65+
| Pull request |
66+
| Push |
67+
68+
## Where can this GitHub App be installed? {% #github-where-installed %}
69+
70+
Check the **Any account** box under **Where can this GitHub App be installed?** section. This is important to allow you to install the GitHub app on multiple Appwrite projects.
71+
72+
## Environment variables {% #github-variables %}
73+
74+
After creating your app, you'll have to configure the following environment variables.
75+
76+
| Variable | Description |
77+
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78+
| `_APP_DOMAIN` | Your main Appwrite domain used to access the Appwrite Console. When setting a public suffix domain, Appwrite will attempt to issue a valid SSL certificate automatically. When used with a dev domain, Appwrite will assign a self-signed SSL certificate. If you're using a proxy for **localhost development**, such as [ngrok](https://ngrok.com/), this will be the domain of your localhost proxy. |
79+
| `_APP_DOMAIN_TARGET` | A hostname to serve as a CNAME target for your Appwrite custom domains. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. If you're using a proxy for **localhost development**, such as [ngrok](https://ngrok.com/), this will be the domain of your localhost proxy, such as `dd65-2405-201-4013-d8d7-b4c5-fb73-39f9-285c.ngrok.io`. |
80+
| `_APP_DOMAIN_FUNCTIONS` | This will be used for system generated [Function Domains](/docs/products/functions/domains). When a function domain is generated, it will be `[UNIQUE_ID].[_APP_DOMAIN_FUNCTIONS]`. If `_APP_DOMAIN_FUNCTIONS` is set to `example.com` for example, the generated domain for functions will be something like `64d4d22db370ae41a32e.example.com`. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. |
81+
| `_APP_DOMAIN_SITES` | This will be used for system generated [Site Domains](/docs/products/sites/domains). When a site domain is generated, it will be `[UNIQUE_ID].[_APP_DOMAIN_SITES]`. If `_APP_DOMAIN_SITES` is set to `example.com` for example, the generated domain for sites will be something like `64d4d22db370ae41a32e.example.com`. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. |
82+
| `_APP_VCS_GITHUB_APP_NAME` | Name of your GitHub app. This is the display name you'll see on GitHub and it will be visible in your GitHub app's URL. |
83+
| `_APP_VCS_GITHUB_PRIVATE_KEY` | RSA private key from GitHub wrapped with double quotes and newlines replaced with `\n`. You can generate private keys from GitHub application settings. |
84+
| `_APP_VCS_GITHUB_APP_ID` | GitHub application ID. You can find it in your GitHub application details. |
85+
| `_APP_VCS_GITHUB_CLIENT_ID` | GitHub client ID. You can find it in your GitHub application details. |
86+
| `_APP_VCS_GITHUB_CLIENT_SECRET` | GitHub client secret. You can generate secrets in your GitHub application settings. |
87+
| `_APP_VCS_GITHUB_WEBHOOK_SECRET` | GitHub webhook secret. You can configure it in your GitHub application settings under webhook section. |
88+
89+
For example, see below.
90+
91+
```bash
92+
_APP_DOMAIN=appwrite.example.com
93+
_APP_DOMAIN_TARGET=appwrite.example.com
94+
_APP_DOMAIN_FUNCTIONS=functions.example.com
95+
_APP_VCS_GITHUB_APP_NAME=my-github-app
96+
_APP_VCS_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAuT8f3lo/X83hfvb0ZN/KD2pl86o/jl3ywKrkj/PQZBmtEv/z\nIugE//sfFoHWc4cizkcji+n3FNU+GEdvMioKuJlPBqPTY8hAbVn7R0geZLpDV/rs\n[...]\n-----END RSA PRIVATE KEY-----"
97+
_APP_VCS_GITHUB_APP_ID=12415
98+
_APP_VCS_GITHUB_CLIENT_ID=Iv1.35asdf43asd
99+
_APP_VCS_GITHUB_CLIENT_SECRET=35rsdse532q13
100+
_APP_VCS_GITHUB_WEBHOOK_SECRET=super-secret
101+
```
102+
103+
[Learn more about environment variables](/docs/advanced/self-hosting/environment-variables)
104+
105+
## Update existing GitHub apps {% #existing-apps %}
106+
107+
There are additional steps if you're updating permissions in existing GitHub apps.
108+
Every time you update your GitHub app's permissions, GitHub will prompt you to review the changes.
109+
You will receive an email and you'll find a prompt under **Settings** > **Integrations** > **Applications** > **Installed GitHub Apps** > find your GitHub app > **Configure**.
110+
You need to accept the new permissions so they're applied to your app.

‎src/routes/docs/advanced/self-hosting/+layout.svelte

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@
2828
label: 'Functions',
2929
href: '/docs/advanced/self-hosting/functions'
3030
},
31+
{
32+
label: 'Sites',
33+
href: '/docs/advanced/self-hosting/sites'
34+
},
3135
{
3236
label: 'Email delivery',
3337
href: '/docs/advanced/self-hosting/email'

‎src/routes/docs/advanced/self-hosting/+page.markdoc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,8 @@ Make these configurations to unlock the full power of Appwrite.
9999

100100
[Configure Appwrite Functions](/docs/advanced/self-hosting/functions)
101101

102+
[Configure Appwrite Sites](/docs/advanced/self-hosting/sites)
103+
102104
[Configure email delivery](/docs/advanced/self-hosting/email)
103105

104106
[Configure SMS delivery](/docs/advanced/self-hosting/sms)
@@ -109,7 +111,7 @@ Make these configurations to unlock the full power of Appwrite.
109111

110112
# Manual (Docker Compose) {% #manual %}
111113

112-
For advanced Docker users, the manual installation might seem more familiar. To set up Appwrite manually, download the Appwrite base [`docker-compose.yml`](https://appwrite.io/install/compose) and [`.env`](https://appwrite.io/install/env) files, then move them inside a directory named `appwrite`. After the download completes, update the different environment variables as you wish in the `.env` file and start the Appwrite stack using the following Docker command:
114+
For advanced Docker users, the manual installation might seem more familiar. To set up Appwrite manually, download the Appwrite base [`docker-compose.yml`](/install/compose) and [`.env`](/install/env) files, then move them inside a directory named `appwrite`. After the download completes, update the different environment variables as you wish in the `.env` file and start the Appwrite stack using the following Docker command:
113115

114116
```bash
115117
docker compose up -d --remove-orphans

‎src/routes/docs/advanced/self-hosting/email/+page.markdoc

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@ If you are looking to send custom emails for promotions, news letters, and other
2121
At this stage, we assume that you have already installed Appwrite. If not, you can follow our [Self Hosting Guide](/docs/advanced/self-hosting) for the installation. Appwrite offers multiple environment variables to customize your server setup to your needs. To configure Appwrite to use your own SMTP server, you need to set the following environment variables in the hidden .env file that comes with your Appwrite installation.
2222

2323
| Environment Variable | Description | Default Value |
24-
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------ |
25-
| _APP_SMTP_HOST | SMTP server host name address. Use an empty string to disable all mail sending from the server. | Empty string |
26-
| _APP_SMTP_PORT | SMTP server TCP port. | Empty |
27-
| _APP_SMTP_SECURE | SMTP secure connection protocol. Change to 'tls' if running on a secure connection. Valid values: empty, 'tls', 'ssl'. | Empty |
28-
| _APP_SMTP_USERNAME | SMTP server user name. | Empty |
29-
| _APP_SMTP_PASSWORD | SMTP server user password. | Empty |
30-
| _APP_SYSTEM_EMAIL_ADDRESS | Configured sender email address, seen by recipients. | "[email protected]" |
24+
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------ |
25+
| `_APP_SMTP_HOST` | SMTP server host name address. Use an empty string to disable all mail sending from the server. | Empty string |
26+
| `_APP_SMTP_PORT` | SMTP server TCP port. | Empty |
27+
| `_APP_SMTP_SECURE` | SMTP secure connection protocol. Change to 'tls' if running on a secure connection. Valid values: empty, 'tls', 'ssl'. | Empty |
28+
| `_APP_SMTP_USERNAME` | SMTP server user name. | Empty |
29+
| `_APP_SMTP_PASSWORD` | SMTP server user password. | Empty |
30+
| `_APP_SYSTEM_EMAIL_ADDRESS` | Configured sender email address, seen by recipients. | "[email protected]" |
3131

3232
Here's a sample configuration if you're using SendGrid as your SMTP provider:
3333

0 commit comments

Comments
 (0)