From a95fd754199e4f2c68f0e8327ac313f72c5a396e Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 1 Feb 2021 11:59:13 +0545 Subject: [PATCH 1/7] WIP --- docs/tutorials/add-environment-variable.md | 52 ++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/tutorials/add-environment-variable.md diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md new file mode 100644 index 000000000..15c3e7126 --- /dev/null +++ b/docs/tutorials/add-environment-variable.md @@ -0,0 +1,52 @@ +# Introducing new Environment Variable + +This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). + +## Getting Started + +### Agenda +Adding new features may require various configurations options to be set by the users. And for such options we use environment variables in Appwrite. + +This tutorial will cover, how to properly add new environment variable in Appwrite. + +## Error Reporting + +By default, Appwrite installation comes with error debugging turned on, We do this to help new users solve issues and report problems while still in development mode. + +In production, it is highly recommended to turn error reporting off. To do so, you have to change the Appwrite container environment variable **_APP_ENV** value from **development** to **production**. + +## Enable Encryption + +By default, the Appwrite setup doesn’t come with a uniquely generated encryption key. This key is used to store your files and sensitive data like webhook passwords or API keys in a safe way. To take advantage of this feature, you must generate a unique key and set it as the value of the **_APP_OPENSSL_KEY_V1** environment variable. + +Make sure to keep this key in a safe place and never make it publicly accessible. There are many [online resources]([https://www.freecodecamp.org/news/how-to-securely-store-api-keys-4ff3ea19ebda/](https://www.freecodecamp.org/news/how-to-securely-store-api-keys-4ff3ea19ebda/)) with methods of keeping your secret keys safe in your servers. + +## Limit Access to your Console + +By default, anyone can signup for your Appwrite server, create projects, and use your computing power. While this is great for testing around or running your Appwrite service in a network isolated environment, it is highly not recommended for public production use. + +We are providing three different methods to limit access to your Appwrite console. You can either set a list of [IPs]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_ips](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_ips)), [email address]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_emails](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_emails)) or [email domains]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_domains](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_domains)) which users are allowed to signup from. You can choose one or multiple restriction methods to apply. + +## Scaling + +Appwrite was built with scalability in mind. Appwrite can potentially scale horizontally infinitely with no known limitations. + +Appwrite uses a few containers to run, where each container has its job. Most of the Appwrite containers are stateless, and in order to scale them, all you need is run multiple instances of them and setup a load balancer in front of them. + +If you decide to set up a load balancer for a specific container, make sure that the containers that are trying to communicate with it are accessing it through a load balancer and not directly. All connections between Appwrite different containers are set using Docker environment variables. + +There are three Appwrite containers that do keep their state are the MariaDB, Redis, and InfluxDB containers that are used for storing data, cache, and stats (in this order). To scale them out, all you need to do is set up a standard cluster (same as you would with any other app using these technologies) according to your needs and performance. + +## Sending Emails + +Sending emails is hard. There are a lot of SPAM rules and configurations to master in order to set a functional SMTP server. The SMTP server that comes packaged with Appwrite is great for development but needs some work done to function well against SPAM filters. You can find some guidelines in this [tutorial]([https://www.digitalocean.com/community/tutorials/how-to-use-an-spf-record-to-prevent-spoofing-improve-e-mail-reliability](https://www.digitalocean.com/community/tutorials/how-to-use-an-spf-record-to-prevent-spoofing-improve-e-mail-reliability)). + +Another **easier option** is to use an ‘SMTP as a service’ product like [Sendgrid]([https://sendgrid.com/](https://sendgrid.com/)) or [Mailgun]([https://www.mailgun.com/](https://www.mailgun.com/)). You can change Appwrite SMTP settings and credentials to any 3rd party provider you like who support SMTP integration using our [Docker environment variables]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#smtp](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#smtp)). Most services offer a decent free tier to get started with. + +## Backups + +Backups are highly recommended for any production environment. Currently, there is not built-in script we provide to do this automatically. To be able to backup your Appwrite server data, stats, and files you will need to do the following. + +1. Create a script to backups and restore your MariaDB Appwrite schema. Note that trying to backup MariaDB using a docker volume backup can result in a corrupted copy of your data. It is recommended to use MariaDB or MySQL built-in tools for this. +2. Create a script to backups and restore your InfluxDB stats. If you don’t care much about your server stats, you can skip this. +3. Create a script to backup Appwrite storage volume. There are many [online resources]([https://blog.ssdnodes.com/blog/docker-backup-volumes/](https://blog.ssdnodes.com/blog/docker-backup-volumes/)) explaining different ways to backup a docker volume. When running on multiple servers, it is very recommended to use an attachable storage point. Some cloud providers offer integrated backups to such attachable mount like GCP, AWS, DigitalOcean, and the list continues. From 10bab0dddcbf129f99db28ffcfcef7eff69227c4 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 1 Feb 2021 12:39:52 +0545 Subject: [PATCH 2/7] adding environment variable first draft --- docs/tutorials/add-environment-variable.md | 46 ++++++---------------- 1 file changed, 11 insertions(+), 35 deletions(-) diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md index 15c3e7126..10b80307b 100644 --- a/docs/tutorials/add-environment-variable.md +++ b/docs/tutorials/add-environment-variable.md @@ -9,44 +9,20 @@ Adding new features may require various configurations options to be set by the This tutorial will cover, how to properly add new environment variable in Appwrite. -## Error Reporting +### Naming environment varialbe +The environment variables in Appwrite is prefixed with `_APP_`. Then if it belongs to specific cateogry, the category name is appended as `_APP_REDIS` for redis category. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. -By default, Appwrite installation comes with error debugging turned on, We do this to help new users solve issues and report problems while still in development mode. +### Describe new environment variable +First of all we add the new environment variable to `app/config/variables.php` under specific category. If none of the categories fit, add it in general category. Copy the existing variables description to create new one so that you will not miss any required fields. -In production, it is highly recommended to turn error reporting off. To do so, you have to change the Appwrite container environment variable **_APP_ENV** value from **development** to **production**. +### Add to .env and Dockerfile +If newly introduced environment variable has a default value, add it to the `.env` and `Dockerfile` along with other environment variables. -## Enable Encryption +### Add to docker compose file and template +Add the new environment variables to the `docker-compose.yml` and `app/views/install/compose.phtml` for each docker services that require access to those environment variables. -By default, the Appwrite setup doesn’t come with a uniquely generated encryption key. This key is used to store your files and sensitive data like webhook passwords or API keys in a safe way. To take advantage of this feature, you must generate a unique key and set it as the value of the **_APP_OPENSSL_KEY_V1** environment variable. +With these steps, your environment variable is properly added and can be accessed inside Appwrite code or any other containers where it is passed. You can access and use those variables to implement the features you are trying to implement. -Make sure to keep this key in a safe place and never make it publicly accessible. There are many [online resources]([https://www.freecodecamp.org/news/how-to-securely-store-api-keys-4ff3ea19ebda/](https://www.freecodecamp.org/news/how-to-securely-store-api-keys-4ff3ea19ebda/)) with methods of keeping your secret keys safe in your servers. +If everything goes well, commit and initiate a PR and wait for the Appwrite team's approval. -## Limit Access to your Console - -By default, anyone can signup for your Appwrite server, create projects, and use your computing power. While this is great for testing around or running your Appwrite service in a network isolated environment, it is highly not recommended for public production use. - -We are providing three different methods to limit access to your Appwrite console. You can either set a list of [IPs]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_ips](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_ips)), [email address]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_emails](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_emails)) or [email domains]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_domains](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#_app_console_whitelist_domains)) which users are allowed to signup from. You can choose one or multiple restriction methods to apply. - -## Scaling - -Appwrite was built with scalability in mind. Appwrite can potentially scale horizontally infinitely with no known limitations. - -Appwrite uses a few containers to run, where each container has its job. Most of the Appwrite containers are stateless, and in order to scale them, all you need is run multiple instances of them and setup a load balancer in front of them. - -If you decide to set up a load balancer for a specific container, make sure that the containers that are trying to communicate with it are accessing it through a load balancer and not directly. All connections between Appwrite different containers are set using Docker environment variables. - -There are three Appwrite containers that do keep their state are the MariaDB, Redis, and InfluxDB containers that are used for storing data, cache, and stats (in this order). To scale them out, all you need to do is set up a standard cluster (same as you would with any other app using these technologies) according to your needs and performance. - -## Sending Emails - -Sending emails is hard. There are a lot of SPAM rules and configurations to master in order to set a functional SMTP server. The SMTP server that comes packaged with Appwrite is great for development but needs some work done to function well against SPAM filters. You can find some guidelines in this [tutorial]([https://www.digitalocean.com/community/tutorials/how-to-use-an-spf-record-to-prevent-spoofing-improve-e-mail-reliability](https://www.digitalocean.com/community/tutorials/how-to-use-an-spf-record-to-prevent-spoofing-improve-e-mail-reliability)). - -Another **easier option** is to use an ‘SMTP as a service’ product like [Sendgrid]([https://sendgrid.com/](https://sendgrid.com/)) or [Mailgun]([https://www.mailgun.com/](https://www.mailgun.com/)). You can change Appwrite SMTP settings and credentials to any 3rd party provider you like who support SMTP integration using our [Docker environment variables]([https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#smtp](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/environment-variables.md#smtp)). Most services offer a decent free tier to get started with. - -## Backups - -Backups are highly recommended for any production environment. Currently, there is not built-in script we provide to do this automatically. To be able to backup your Appwrite server data, stats, and files you will need to do the following. - -1. Create a script to backups and restore your MariaDB Appwrite schema. Note that trying to backup MariaDB using a docker volume backup can result in a corrupted copy of your data. It is recommended to use MariaDB or MySQL built-in tools for this. -2. Create a script to backups and restore your InfluxDB stats. If you don’t care much about your server stats, you can skip this. -3. Create a script to backup Appwrite storage volume. There are many [online resources]([https://blog.ssdnodes.com/blog/docker-backup-volumes/](https://blog.ssdnodes.com/blog/docker-backup-volumes/)) explaining different ways to backup a docker volume. When running on multiple servers, it is very recommended to use an attachable storage point. Some cloud providers offer integrated backups to such attachable mount like GCP, AWS, DigitalOcean, and the list continues. +Whooho! you have successfully added new environment variable to Appwrite. \ No newline at end of file From dccd44a1c6e1a2aea17b264a31aca4858f5d7864 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 1 Feb 2021 15:37:50 +0545 Subject: [PATCH 3/7] updated docs as suggested in review --- docs/tutorials/add-environment-variable.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md index 10b80307b..1e0f67ff7 100644 --- a/docs/tutorials/add-environment-variable.md +++ b/docs/tutorials/add-environment-variable.md @@ -10,19 +10,23 @@ Adding new features may require various configurations options to be set by the This tutorial will cover, how to properly add new environment variable in Appwrite. ### Naming environment varialbe -The environment variables in Appwrite is prefixed with `_APP_`. Then if it belongs to specific cateogry, the category name is appended as `_APP_REDIS` for redis category. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. +The environment variables in Appwrite is prefixed with `_APP_`. Then if it belongs to specific cateogry, the category name is appended as `_APP_REDIS` for redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage and Functions. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. You can find more information on available categories and existing environment variables at [environment variables doc](https://appwrite.io/docs/environment-variables). ### Describe new environment variable First of all we add the new environment variable to `app/config/variables.php` under specific category. If none of the categories fit, add it in general category. Copy the existing variables description to create new one so that you will not miss any required fields. +These information are also used to generate the website documentation at https://appwrite.io/docs/environment-variables, so please use proper information that clearly defines the purpose and other required info about the environment variable that you are adding. + ### Add to .env and Dockerfile -If newly introduced environment variable has a default value, add it to the `.env` and `Dockerfile` along with other environment variables. +If newly introduced environment variable has a default value, add it to the `.env` and `Dockerfile` along with other environment variables. `.env` file uses settings for Appwrite development environment. ### Add to docker compose file and template Add the new environment variables to the `docker-compose.yml` and `app/views/install/compose.phtml` for each docker services that require access to those environment variables. +The `docker-compose.yml` file is used by the Appwrite maintainers during development where as `app/views/install/compose.phtml` file is used by the Appwrite setup script. + With these steps, your environment variable is properly added and can be accessed inside Appwrite code or any other containers where it is passed. You can access and use those variables to implement the features you are trying to implement. If everything goes well, commit and initiate a PR and wait for the Appwrite team's approval. -Whooho! you have successfully added new environment variable to Appwrite. \ No newline at end of file +Whooho! you have successfully added new environment variable to Appwrite. 🎉 \ No newline at end of file From 2d3b6ed320559ac5eb12bc182087c9208558f142 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 2 Feb 2021 11:14:09 +0545 Subject: [PATCH 4/7] grammar updates --- docs/tutorials/add-environment-variable.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md index 1e0f67ff7..e77dd43bb 100644 --- a/docs/tutorials/add-environment-variable.md +++ b/docs/tutorials/add-environment-variable.md @@ -7,13 +7,13 @@ This document is part of the Appwrite contributors' guide. Before you continue r ### Agenda Adding new features may require various configurations options to be set by the users. And for such options we use environment variables in Appwrite. -This tutorial will cover, how to properly add new environment variable in Appwrite. +This tutorial will cover, how to properly add a new environment variable in Appwrite. ### Naming environment varialbe -The environment variables in Appwrite is prefixed with `_APP_`. Then if it belongs to specific cateogry, the category name is appended as `_APP_REDIS` for redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage and Functions. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. You can find more information on available categories and existing environment variables at [environment variables doc](https://appwrite.io/docs/environment-variables). +The environment variables in Appwrite are prefixed with `_APP_`. If it belongs to a specific cateogry, the category name is appended as `_APP_REDIS` for the redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage and Functions. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. You can find more information on available categories and existing environment variables at [environment variables doc](https://appwrite.io/docs/environment-variables). ### Describe new environment variable -First of all we add the new environment variable to `app/config/variables.php` under specific category. If none of the categories fit, add it in general category. Copy the existing variables description to create new one so that you will not miss any required fields. +First of all, we add the new environment variable to `app/config/variables.php` in the designated category. If none of the categories fit, add it to the General category. Copy the existing variables description to create a new one, so that you will not miss any required fields. These information are also used to generate the website documentation at https://appwrite.io/docs/environment-variables, so please use proper information that clearly defines the purpose and other required info about the environment variable that you are adding. @@ -25,8 +25,8 @@ Add the new environment variables to the `docker-compose.yml` and `app/views/ins The `docker-compose.yml` file is used by the Appwrite maintainers during development where as `app/views/install/compose.phtml` file is used by the Appwrite setup script. -With these steps, your environment variable is properly added and can be accessed inside Appwrite code or any other containers where it is passed. You can access and use those variables to implement the features you are trying to implement. +With these steps, your environment variable is properly added and can be accessed inside Appwrite code and any other containers where it is passed. You can access and use those variables to implement the features you are trying to achieve. -If everything goes well, commit and initiate a PR and wait for the Appwrite team's approval. +If everything went well, commit and initiate a PR and wait for the Appwrite team's approval. Whooho! you have successfully added new environment variable to Appwrite. 🎉 \ No newline at end of file From ab324f3c83ed1cc349620ec74e83df74ad3e6694 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 8 Feb 2021 11:00:44 +0545 Subject: [PATCH 5/7] Update docs/tutorials/add-environment-variable.md Co-authored-by: Christy Jacob --- docs/tutorials/add-environment-variable.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md index e77dd43bb..cdc728bc8 100644 --- a/docs/tutorials/add-environment-variable.md +++ b/docs/tutorials/add-environment-variable.md @@ -10,7 +10,7 @@ Adding new features may require various configurations options to be set by the This tutorial will cover, how to properly add a new environment variable in Appwrite. ### Naming environment varialbe -The environment variables in Appwrite are prefixed with `_APP_`. If it belongs to a specific cateogry, the category name is appended as `_APP_REDIS` for the redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage and Functions. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. You can find more information on available categories and existing environment variables at [environment variables doc](https://appwrite.io/docs/environment-variables). +The environment variables in Appwrite are prefixed with `_APP_`. If it belongs to a specific cateogry, the category name is appended as `_APP_REDIS` for the redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage and Functions. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. You can find more information on available categories and existing environment variables in the [environment variables doc](https://appwrite.io/docs/environment-variables). ### Describe new environment variable First of all, we add the new environment variable to `app/config/variables.php` in the designated category. If none of the categories fit, add it to the General category. Copy the existing variables description to create a new one, so that you will not miss any required fields. @@ -29,4 +29,4 @@ With these steps, your environment variable is properly added and can be accesse If everything went well, commit and initiate a PR and wait for the Appwrite team's approval. -Whooho! you have successfully added new environment variable to Appwrite. 🎉 \ No newline at end of file +Whooho! you have successfully added new environment variable to Appwrite. 🎉 From 8b57b236340e54cfadb3a1226473a9e70458e2dc Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 8 Feb 2021 11:01:20 +0545 Subject: [PATCH 6/7] Update docs/tutorials/add-environment-variable.md Co-authored-by: Christy Jacob --- docs/tutorials/add-environment-variable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md index cdc728bc8..af997870f 100644 --- a/docs/tutorials/add-environment-variable.md +++ b/docs/tutorials/add-environment-variable.md @@ -15,7 +15,7 @@ The environment variables in Appwrite are prefixed with `_APP_`. If it belongs t ### Describe new environment variable First of all, we add the new environment variable to `app/config/variables.php` in the designated category. If none of the categories fit, add it to the General category. Copy the existing variables description to create a new one, so that you will not miss any required fields. -These information are also used to generate the website documentation at https://appwrite.io/docs/environment-variables, so please use proper information that clearly defines the purpose and other required info about the environment variable that you are adding. +This information is also used to generate the website documentation at https://appwrite.io/docs/environment-variables, so please use good descriptions that clearly define the purpose and other required info about the environment variable that you are adding. ### Add to .env and Dockerfile If newly introduced environment variable has a default value, add it to the `.env` and `Dockerfile` along with other environment variables. `.env` file uses settings for Appwrite development environment. From 8e225681b9ee598f19c86f0389a8a503c9532da7 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 8 Feb 2021 11:03:41 +0545 Subject: [PATCH 7/7] updated from suggestion --- docs/tutorials/add-environment-variable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md index af997870f..505cf4aaa 100644 --- a/docs/tutorials/add-environment-variable.md +++ b/docs/tutorials/add-environment-variable.md @@ -10,7 +10,7 @@ Adding new features may require various configurations options to be set by the This tutorial will cover, how to properly add a new environment variable in Appwrite. ### Naming environment varialbe -The environment variables in Appwrite are prefixed with `_APP_`. If it belongs to a specific cateogry, the category name is appended as `_APP_REDIS` for the redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage and Functions. Finally the properly describing name is given to the variable as `_APP_REDIS_HOST` for redis host. You can find more information on available categories and existing environment variables in the [environment variables doc](https://appwrite.io/docs/environment-variables). +The environment variables in Appwrite are prefixed with `_APP_`. If it belongs to a specific cateogry, the category name is appended as `_APP_REDIS` for the redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage and Functions. Finally a properly describing name is given to the variable. For example `_APP_REDIS_HOST` is an environment variable for redis connection host. You can find more information on available categories and existing environment variables in the [environment variables doc](https://appwrite.io/docs/environment-variables). ### Describe new environment variable First of all, we add the new environment variable to `app/config/variables.php` in the designated category. If none of the categories fit, add it to the General category. Copy the existing variables description to create a new one, so that you will not miss any required fields.