Skip to content
This repository was archived by the owner on Sep 29, 2023. It is now read-only.

Commit 1e0780f

Browse files
author
Vincent (Wen Yu) Ge
authored
Merge pull request #424 from appwrite/github-app-permissions
Add github app config information
2 parents 929b8d1 + 8e8153f commit 1e0780f

8 files changed

+165
-23
lines changed

‎app/views/docs/authentication-management.phtml

+2-2
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,7 @@ let prefs = try await account.getPrefs()</code></pre>
204204

205205
<h2><a href="#labels" id="labels">Labels</a></h2>
206206
<p>
207-
Labels are a good way to flag a user to grant them access to resources.
207+
Labels are a good way to categorize a user to grant them access to resources.
208208
For example, a <code>subscriber</code> label can be added to a user once they've purchased a subscription.
209209
</p>
210210

@@ -414,7 +414,7 @@ var response = await users.UpdateLabels(
414414
</p>
415415

416416
<p>
417-
For example, in a todo app, a user can <a href="docs/client/teams#teamsCreate">create a team</a> for one of their todo lists and <a href="/docs/client/teams#teamsCreateMembership">invite another user</a> to the team to grant the other user access.
417+
For example, in a todo app, a user can <a href="/docs/client/teams#teamsCreate">create a team</a> for one of their todo lists and <a href="/docs/client/teams#teamsCreateMembership">invite another user</a> to the team to grant the other user access.
418418
The invited user can <a href="/docs/client/teams#teamsUpdateMembershipStatus">accept the invitation</a> to gain access.
419419
If the user's ever removed from the team, they'll lose access again.
420420
</p>

‎app/views/docs/configuration.phtml

+149-8
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,143 @@
2222
<h2><a href="#git" id="git">Configure GitHub App</a></h2>
2323
<p>
2424
Appwrite supports automatic deployments through Git integration.
25-
In order for Appwrite to access your repos, you must configure a GitHub app to enable this integration.
25+
In order for Appwrite to access your repos, you must <a href="https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps" target="_blank" rel="noopener">create a GitHub app</a> to enable this integration.
26+
The GitHub app requires the following configurations.
2627
</p>
2728

28-
<p>You'll have to configure the following environment variables.</p>
29+
<p>
30+
For automatic Git deployment to work, Appwrite needs to receive communication from GitHub, this means your Appwrite project must be accessible on the internet.
31+
If you're running on <code>localhost</code>, you need to run a proxy like <a href="https://ngrok.com/" target="_blank" rel="noopener">ngrok</a>.
32+
</p>
33+
34+
<h3><a href="#callback" id="callback">Callback URL</a></h3>
35+
<p>
36+
GitHub will use <b>callback URLs</b> to redirect users back to Appwrite.
37+
Set these callback URLs under <b>Identifying and authorizing users</b>.
38+
</p>
39+
<table class="full">
40+
<thead>
41+
<tr>
42+
<td>URLs</td>
43+
</tr>
44+
</thead>
45+
<tbody>
46+
<tr>
47+
<td><code>http://[HOSTNAME_OR_IP]/v1/vcs/github/callback</code></td>
48+
</tr>
49+
<tr>
50+
<td><code>http://[HOSTNAME_OR_IP]/v1/account/sessions/oauth2/callback/github/console</code></td>
51+
</tr>
52+
</tbody>
53+
</table>
54+
55+
<h3><a href="#post-install" id="post-install">Post Installation</a></h3>
56+
<p>
57+
Check the <b>Redirect on update</b> box under the <b>Post installation</b> section.
58+
</p>
59+
60+
61+
<h3><a href="#github-webhooks" id="github-webhooks">Webhook</a></h3>
62+
<p>
63+
GitHub will notify Appwrite about events like new commits using webhooks.
64+
Under <b>Webhook</b>, you need to check the <b>Active</b> checkbox.
65+
You also need to set the <b>Webhook URL</b> as <code>https://[HOSTNAME_OR_IP]/v1/vcs/github/events</code>.
66+
</p>
67+
68+
<p>
69+
If you're running Appwrite on <code>localhost</code>, GitHub can't send requests to Appwrite through webhooks and automatic deployments won't work.
70+
You'll need host Appwrite on a server or use a proxy like <a href="https://ngrok.com/" target="_blank" rel="noopener">ngrok</a> to make Appwrite accessible to GitHub.
71+
</p>
72+
73+
<h3><a href="#repository-permission" id="repository-permission">Repository Permissions</a></h3>
74+
<p>
75+
Configure these permissions under the <b>Repository permission</b> dropdown.
76+
</p>
77+
<table class="full">
78+
<thead>
79+
<tr>
80+
<td>Permission</td>
81+
<td>Access</td>
82+
</tr>
83+
</thead>
84+
<tbody>
85+
<tr>
86+
<td>Administration</td>
87+
<td>Read and write</td>
88+
</tr>
89+
<tr>
90+
<td>Checks</td>
91+
<td>Read and write.</td>
92+
</tr>
93+
<tr>
94+
<td>Commit Statuses</td>
95+
<td>Read and write</td>
96+
</tr>
97+
<tr>
98+
<td>Contents</td>
99+
<td>Read and write</td>
100+
</tr>
101+
<tr>
102+
<td>Issues</td>
103+
<td>Read and write</td>
104+
</tr>
105+
<tr>
106+
<td>Metadata</td>
107+
<td>Read-only</td>
108+
</tr>
109+
<tr>
110+
<td>Pull requests</td>
111+
<td>Read and write</td>
112+
</tr>
113+
<tr>
114+
<td>Webhooks</td>
115+
<td>Read and write</td>
116+
</tr>
117+
</tbody>
118+
</table>
119+
120+
<h3><a href="#account-permission" id="account-permission">Account Permissions</a></h3>
121+
<p>
122+
Configure these permissions under the <b>Account Permission</b> dropdown.
123+
</p>
124+
<table class="full">
125+
<thead>
126+
<tr>
127+
<td>Permission</td>
128+
<td>Access</td>
129+
</tr>
130+
</thead>
131+
<tbody>
132+
<tr>
133+
<td>Email address</td>
134+
<td>Read-only</td>
135+
</tr>
136+
</tbody>
137+
</table>
138+
139+
<h3><a href="#subscribe-events" id="subscribe-events">Subscribe to Events</a></h3>
140+
<p>
141+
Select these under the <b>Subscribe to events</b> dropdown.
142+
</p>
143+
<table class="full">
144+
<thead>
145+
<tr>
146+
<td>Event</td>
147+
<td></td>
148+
<td></td>
149+
</tr>
150+
</thead>
151+
<tbody>
152+
<tr>
153+
<td>Pull request</td>
154+
<td>Push</td>
155+
<td></td>
156+
</tr>
157+
</tbody>
158+
</table>
159+
160+
<h3><a href="#github-variables" id="github-variables">Environment Variables</a></h3>
161+
<p>After creating your app, you'll have to configure the following environment variables.</p>
29162

30163
<table class="full">
31164
<thead>
@@ -37,7 +170,7 @@
37170
<tbody>
38171
<tr>
39172
<td>_APP_VCS_GITHUB_APP_NAME</td>
40-
<td>Name of your GitHub app. This value should be set to your GitHub application's URL.</td>
173+
<td>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.</td>
41174
</tr>
42175
<tr>
43176
<td>_APP_VCS_GITHUB_PRIVATE_KEY</td>
@@ -64,6 +197,14 @@
64197

65198
<p><a href="/docs/environment-variables"><i class="icon-angle-circled-right margin-start-negative-tiny margin-end-tiny"></i> Learn more about environment variables</a></p>
66199

200+
<h3><a href="#existing-apps" id="existing-apps">Update Existing GitHub Apps</a></h3>
201+
<p>
202+
There are additional steps if you're updating permissions in existing GitHub apps.
203+
Every time you update your GitHub app's permissions, GitHub will prompt you to review the changes.
204+
You will receive an email and you'll find a prompt under <b>Settings</b> > <b>Integrations</b> > <b>Applications</b> > <b>Installed GitHub Apps</b> > find your GitHub app > <b>Configure</b>.
205+
You need to accept the new permissions so they're applied to your app.
206+
</p>
207+
67208
<h2><a href="#functions" id="functions">Configure Function Runtimes</a></h2>
68209
<p>
69210
Not all function runtimes are enabled by default. Enable the runtimes that you need and disable unused runtimes to save disk space on your server.
@@ -80,18 +221,18 @@
80221

81222
<p>You can find a full list of supported runtimes on the <a href="/docs/environment-variables#functions">environment variables</a> page.</p>
82223

83-
<p>You can also configure the maximum timeout that can be set on individual Appwrite functions. The maximum configurable timeout can be increased by changing the <code>_APP_FUNCTIONS_TIMEOUT</code> environment variable. This environment variable changes the configurable maximum but does not alter existing individual configurations.</p>
224+
<p>You can also configure the maximum timeout that can be set on individual Appwrite functions. The maximum configurable timeout can be increased by changing the <code>_APP_FUNCTIONS_TIMEOUT</code> environment variable. This environment variable changes the configurable maximum but does not alter existing configurations of individual functions.</p>
84225

85-
<h2><a href="#storage" id="storage">Storage Adaptors</a></h2>
226+
<h2><a href="#storage" id="storage">Storage Adapters</a></h2>
86227
<p>Appwrite's Storage Service can be configured to store files locally, or with self-hosted and cloud storage services. By default, Appwrite's Storage Service <b>stores files on your server's local storage</b>. If you expect large volumes of data or the need to have scalable data storage, you may choose to use a separate storage service.</p>
87228

88-
<p>Appwrite supports AWS S3, Digital Ocean Spaces, Backblaze, Akamai Object Storage, and Wasabi as storage adaptors. Some of these services can be self-hosted, just like Appwrite.</p>
229+
<p>Appwrite supports AWS S3, Digital Ocean Spaces, Backblaze, Akamai Object Storage, and Wasabi as storage adapters. Some of these services can be self-hosted, just like Appwrite.</p>
89230

90-
<p>You can select which storage adaptor to use by setting the <code>_APP_STORAGE_DEVICE</code> environment variable. Valid values are <code>local</code>, <code>s3</code>, <code>dospaces</code>, <code>backblaze</code>, <code>linode</code> and <code>wasabi</code>. Each storage adaptor requires its own set of additional environment variables to configure.</p>
231+
<p>You can select which storage adapter to use by setting the <code>_APP_STORAGE_DEVICE</code> environment variable. Valid values are <code>local</code>, <code>s3</code>, <code>dospaces</code>, <code>backblaze</code>, <code>linode</code>, and <code>wasabi</code>. Each storage adapter requires its own set of additional environment variables to configure.</p>
91232

92233
<p>The maximum size for individual file uploads is controlled by the <code>_APP_STORAGE_LIMIT</code> environment variable, which defaults to 30 MB. See <a href="/docs/environment-variables#storage">Environment Variables</a> for more information.</p>
93234

94-
<p><a href="/docs/environment-variables#storage"><i class="icon-angle-circled-right margin-start-negative-tiny margin-end-tiny"></i> Configure storage adaptors</a></p>
235+
<p><a href="/docs/environment-variables#storage"><i class="icon-angle-circled-right margin-start-negative-tiny margin-end-tiny"></i> Configure storage adapters</a></p>
95236

96237
<h2><a href="#apply-changes" id="apply-changes">Applying Changes</a></h2>
97238
<p>After editing your <code>docker-compose.yml</code> or <code>.env</code> files, you will need to recreate your Appwrite stack by running the following compose command in your terminal.</p>

‎app/views/docs/databases.phtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
<h2><a href="/docs/databases#databases" id="databases">Create Your Databases</a></h2>
1313
<p>
14-
Appwrite's Databases Service allows you to create multiple databases. Each database can contain many collections and can be backed by a different database adaptor in future versions.
14+
Appwrite's Databases Service allows you to create multiple databases. Each database can contain many collections and can be backed by a different database adapter in future versions.
1515
</p>
1616

1717
<p>

‎app/views/docs/email-and-sms-templates.phtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
depending on the configured locale.
77
</p>
88

9-
<h2><a href="#smtp" id="#smtp">Custom SMTP server</a></h2>
9+
<h2><a href="#smtp" id="smtp">Custom SMTP server</a></h2>
1010
<p>
1111
Appwrite Cloud has a default SMTP server to get you started.
1212
This SMTP server sends generic emails and doesn't allow customizing SMTP templates.

‎app/views/docs/functions-deploy.phtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@
7171
<h2><a href="#cli" id="cli">CLI</a></h2>
7272
<div class="notice margin-bottom-small">
7373
<h2>CLI Setup</h2>
74-
<p>Before you can deploy with the Appwrite CLI, make sure you've <a href="docs/command-line">installed and initialized</a> the CLI.</p>
74+
<p>Before you can deploy with the Appwrite CLI, make sure you've <a href="/docs/command-line">installed and initialized</a> the CLI.</p>
7575
</div>
7676
<p>
7777
To deploy with the Appwrite CLI, your function must be added to <code>appwrite.json</code> that tells the CLI where each function is stored.

‎app/views/docs/functions-develop.phtml

+6-6
Original file line numberDiff line numberDiff line change
@@ -2637,32 +2637,32 @@ public class Main {
26372637
<li>
26382638
The parameter passed into functions has changed.
26392639
<code>req</code> and <code>res</code> has been replaced by <code>context</code>, which contains new logger methods.
2640-
<a href="docs/functions-develop#context">Learn about context.</a>
2640+
<a href="/docs/functions-develop#context">Learn about context.</a>
26412641
</li>
26422642
<li>
26432643
To improve privacy and logging reliability, we provide new <code>context.log()</code> and <code>context.error()</code> functions.
26442644
You can no longer use native logging methods.
2645-
<a href="docs/functions-develop#logging">Learn about logging.</a>
2645+
<a href="/docs/functions-develop#logging">Learn about logging.</a>
26462646
</li>
26472647
<li>
26482648
The old way of <code>req.variables</code> has been deprecated.
26492649
You can now access variables passed into each function as environment variables.
2650-
<a href="docs/functions-develop#environment-variables">Learn about environment variables.</a>
2650+
<a href="/docs/functions-develop#environment-variables">Learn about environment variables.</a>
26512651
</li>
26522652
<li>
26532653
The <code>req</code> object has been updated to use terminology consistent with typical HTTP concepts.
26542654
You'll now find familiar concepts like headers, body, HTTP methods, and others.
2655-
<a href="docs/functions-develop#request">Learn about request.</a>
2655+
<a href="/docs/functions-develop#request">Learn about request.</a>
26562656
</li>
26572657
<li>
26582658
The response object has been updated.
26592659
You can now specify headers, as well as use new methods like return redirects or empty responses.
2660-
<a href="docs/functions-develop#response">Learn about response.</a>
2660+
<a href="/docs/functions-develop#response">Learn about response.</a>
26612661
</li>
26622662
<li>
26632663
Now, you <b>must return a response</b> such as <code>return context.res.send("")</code>.
26642664
This prevents confusing errors when functions are terminated prematurely before a response is sent.
2665-
<a href="docs/functions-develop#response">Learn about response.</a>
2665+
<a href="#response">Learn about response.</a>
26662666
</li>
26672667
<li>
26682668
Some variables about how a function was triggered are now found in the <code>context.req</code> object as <a href="/docs/functions-develop#request">headers</a>.

‎app/views/docs/migrations-firebase.phtml

+4-3
Original file line numberDiff line numberDiff line change
@@ -143,12 +143,13 @@
143143
Click <b>Add Key</b> and select <b>Create new key</b>. Select <b>JSON</b> as the key type and click <b>Create</b>. This will download a JSON file to your computer.
144144
</li>
145145
<li>
146-
Upload the JSON file to Appwrite and follow the migration wizard.
146+
Upload the JSON file to Appwrite and follow the migration wizard to select which resource you need to migrate.
147147
</li>
148148
<li>
149-
After completing the migration wizard, migration will begin. Return to step 4 of <a href="#migration-process">the migration steps</a>.
149+
After completing the migration wizard, migration will begin. This will run in the background, you can close the browser.</a>.
150150
</li>
151151
<li>
152-
Finally, add the platforms for your <a href="/docs/getting-started-for-web">Web</a>, <a href="getting-started-for-flutter/docs/getting-started-for-flutter">Flutter</a>, <a href="/docs/getting-started-for-android">Android</a>, and <a href="/docs/getting-started-for-apple">iOS</a> apps.
152+
Finally, add the platforms for your <a href="/docs/getting-started-for-web">Web</a>, <a href="getting-started-for-flutter/docs/getting-started-for-flutter">Flutter</a>, <a href="/docs/getting-started-for-android">Android</a>, and <a href="/docs/getting-started-for-apple">iOS</a> apps.
153+
Also remember to <a href="/docs/permissions">add appropriate permissions</a></b> to the migrated resources to protect user data and privacy.
153154
</li>
154155
</ol>

‎app/views/docs/self-hosting.phtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@
121121
</table>
122122

123123
<h2><a href="#next-steps" id="next-steps">Next Steps</a></h2>
124-
<p>Self-hosting Appwrite gives you more configurable options. You can customize Appwrite with your choice of S3 compatible storage adaptors, email and SMS providers, functions runtimes, and more.</p>
124+
<p>Self-hosting Appwrite gives you more configurable options. You can customize Appwrite with your choice of S3 compatible storage adapters, email and SMS providers, functions runtimes, and more.</p>
125125

126126
<p><a href="/docs/configuration"><i class="icon-angle-circled-right margin-start-negative-tiny margin-end-tiny"></i> Learn about configuring Appwrite</a></p>
127127

0 commit comments

Comments
 (0)