diff --git a/docs/references/selfhosting.md b/docs/references/selfhosting.md index 9aba1d87e..05aad1104 100644 --- a/docs/references/selfhosting.md +++ b/docs/references/selfhosting.md @@ -2,21 +2,21 @@ The Cloudron platform can be installed on public cloud servers from EC2, Digital Ocean, Hetzner, Linode, OVH, Scaleway, Vultr etc. Running Cloudron on a home server or company intranet is work -in progress. +in progress. If you run into any trouble following this guide, ask us at our [chat](https://chat.cloudron.io). # Understand -Before installing the Cloudron, it is helpful to understand Cloudron's design. The Cloudron +Before installing the Cloudron, it is helpful to understand Cloudron's design. The Cloudron intends to make self-hosting effortless. It takes care of updates, backups, firewall, dns setup, certificate management etc. All app and user configuration is carried out using the web interface. This approach to self-hosting means that the Cloudron takes complete ownership of the server and only tracks changes that were made via the web interface. Any external changes made to the server -(i.e other than via the Cloudron web interface) may be lost across updates. +(i.e other than via the Cloudron web interface or API) may be lost across updates. -The Cloudron requires a domain name when it is installed. Apps are installed into subdomains. +The Cloudron requires a domain name when it is installed. Apps are installed into subdomains. The `my` subdomain is special and is the location of the Cloudron web interface. For this to work, the Cloudron requires a way to programmatically configure the DNS entries of the domain. Note that the Cloudron will never overwrite _existing_ DNS entries and refuse to install @@ -43,14 +43,14 @@ See [#14](https://git.cloudron.io/cloudron/cloudron-cli/issues/14) for more info ## Windows -The CLI tool does not work on Windows. +The CLI tool does not work on Windows. Please contact us on our [chat](https://chat.cloudron.io) if you want to help with Windows support. # Installing ## Choose Domain A domain name is required when installing the Cloudron. Currently, only Second Level Domains -are supported. For example, `example.com`, `example.co.uk` will work fine. Choosing a domain +are supported. For example, `example.com`, `example.co.uk` will work fine. Choosing a domain name at any other level like `cloudron.example.com` will not work. The domain name must use one of the following name servers: @@ -63,17 +63,17 @@ You will have to provide the DNS API credentials after you complete the installa ## Create server -Create an `Ubuntu 16.04 (Xenial)` server with at-least `1gb` RAM. Do not make any changes +Create an `Ubuntu 16.04 (Xenial)` server with at-least `1gb` RAM. Do not make any changes to vanilla ubuntu. Be sure to allocate a static IPv4 address for your server. ### Linode -Since Linode does not manage SSH keys, be sure to add the public key to +Since Linode does not manage SSH keys, be sure to add the public key to `/root/.ssh/authorized_keys`. ### Scaleway -Use the [boot script](https://github.com/scaleway-community/scaleway-docker/issues/2) to +Use the [boot script](https://github.com/scaleway-community/scaleway-docker/issues/2) to enable memory accouting. ## Setup `my` subdomain @@ -101,9 +101,9 @@ Domains are supported. For example, `example.com`, `example.co.uk`, `example.roc work fine. Choosing a domain name at any other level like `cloudron.example.com` will not work. -* `--provider` is the name of your VPS provider. If the name is not on the list, simply -choose `generic`. If the Cloudron does not complete initialization, it may mean that -we have to add some vendor specific quirks. Please open a +* `--provider` is the name of your VPS provider. If the name is not on the list, simply +choose `generic`. If the Cloudron does not complete initialization, it may mean that +we have to add some vendor specific quirks. Please open a [bug report](https://git.cloudron.io/cloudron/box/issues) in that case. Optional arguments used for update and restore: @@ -130,7 +130,7 @@ Once the setup is done, you can access the admin page in the future at `https:// ## DNS -Cloudron has to be given the API credentials for configuring your domain under `Certs & Domains` +Cloudron has to be given the API credentials for configuring your domain under `Certs & Domains` in the web UI. ### Route 53 @@ -185,15 +185,15 @@ backups have the prefix `appbackup_`. The platform state is backed up independen prefix `backup_`. By default, backups reside in `/var/backups`. Having backups reside in the same location as the -server instance is dangerous and it must be changed to an external storage location like `S3` -as soon as possible. +server instance is dangerous and it must be changed to an external storage location like `S3` +as soon as possible. ### S3 Provide S3 backup credentials in the `Settings` page. -Create a bucket in S3. The bucket can be setup to periodically delete old backups by -adding a lifecycle rule using the AWS console. S3 supports both permanent deletion +Create a bucket in S3. The bucket can be setup to periodically delete old backups by +adding a lifecycle rule using the AWS console. S3 supports both permanent deletion or moving objects to the cheaper Glacier storage class based on an age attribute. With the current daily backup schedule a setting of two days should be sufficient for most use-cases. @@ -224,11 +224,12 @@ for most use-cases. Cloudron has a built-in email server. By default, it only sends out email on behalf of apps (for example, password reset or notification). You can enable the email server for sending -and receiving mail on the `settings` page. +and receiving mail on the `settings` page. This feature is only available if you have setup +a DNS provider like Digital Ocean or Route53. Your server's IP plays a big role in how emails from our Cloudron get handled. Spammers -frequently abuse public IP addresses and as a result your Cloudron might possibly start -out with a bad reputation. The good news is that most IP based blacklisting services cool +frequently abuse public IP addresses and as a result your Cloudron might possibly start +out with a bad reputation. The good news is that most IP based blacklisting services cool down over time. The Cloudron sets up DNS entries for SPF, DKIM, DMARC automatically and reputation should be easy to get back. @@ -239,7 +240,7 @@ reputation should be easy to get back. * AWS/EC2 - Fill the PTR [request form](https://aws-portal.amazon.com/gp/aws/html-forms-controller/contactus/ec2-email-limit-rdns-request. * Digital Ocean - Digital Ocean sets up a PTR record based on the droplet's name. So, simply rename - your droplet to `my.`. + your droplet to `my.`. * Scaleway - Edit your security group to allow email. You can also set a PTR record on the interface with your `my.`. @@ -258,15 +259,15 @@ The Cloudron platform itself updates in two ways: update or upgrade. ### Update -An **update** is applied onto the running server instance. Such updates are performed +An **update** is applied onto the running server instance. Such updates are performed every night. You can also use the Cloudron UI to initiate an update immediately. -The Cloudron will always make a complete backup before attempting an update. In the unlikely, +The Cloudron will always make a complete backup before attempting an update. In the unlikely case an update fails, it can be [restored](/references/selfhosting.html#restore). ### Upgrade -An **upgrade** requires a new OS image and thus involves creating the Cloudron from scratch. +An **upgrade** requires a new OS image and thus involves creating the Cloudron from scratch. This process involves creating a new server with the latest code and restoring it from the last backup. @@ -301,10 +302,10 @@ To restore a Cloudron from a specific backup: # Debug -You can [SSH](#ssh) into your Cloudron and collect logs. +You can SSH into your Cloudron and collect logs: * `journalctl -a -u box -u cloudron-installer` to get debug output of box related code. -* `docker ps` will give you the list of containers. The addon containers are named as `mail`, `postgresql`, +* `docker ps` will give you the list of containers. The addon containers are named as `mail`, `postgresql`, `mysql` etc. If you want to get a specific container's log output, `journalctl -a CONTAINER_ID=`. # Help