370 lines
16 KiB
Markdown
370 lines
16 KiB
Markdown
# Overview
|
|
|
|
The Cloudron platform can be installed on public cloud servers from EC2, Digital Ocean, Hetzner,
|
|
Linode, OVH, Scaleway, Vultr etc. Cloudron also runs well on a home server or company intranet.
|
|
|
|
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
|
|
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 or API) may be lost across updates.
|
|
|
|
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
|
|
apps on existing subdomains.
|
|
|
|
# Cloud Server
|
|
|
|
DigitalOcean and EC2 (Amazon Web Services) are frequently tested by us.
|
|
|
|
Please use the below links to support us with referrals:
|
|
* [Amazon EC2](https://aws.amazon.com/ec2/)
|
|
* [DigitalOcean](https://m.do.co/c/933831d60a1e)
|
|
|
|
In addition to those, the Cloudron community has successfully installed the platform on those providers:
|
|
* [Amazon Lightsail](https://amazonlightsail.com/)
|
|
* [hosttech](https://www.hosttech.ch/?promocode=53619290)
|
|
* [Linode](https://www.linode.com/?r=f68d816692c49141e91dd4cef3305da457ac0f75)
|
|
* [OVH](https://www.ovh.com/)
|
|
* [Scaleway](https://www.scaleway.com/)
|
|
* [So you Start](https://www.soyoustart.com/)
|
|
* [Vultr](http://www.vultr.com/?ref=7063201)
|
|
|
|
Please let us know if any of them requires tweaks or adjustments.
|
|
|
|
# Installing
|
|
|
|
## Create server
|
|
|
|
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
|
|
`/root/.ssh/authorized_keys`.
|
|
|
|
### Scaleway
|
|
|
|
Use the [boot script](https://github.com/scaleway-community/scaleway-docker/issues/2) to
|
|
enable memory accouting.
|
|
|
|
## Run setup
|
|
|
|
SSH into your server and run the following commands:
|
|
|
|
```
|
|
wget https://cloudron.io/cloudron-setup
|
|
chmod +x cloudron-setup
|
|
./cloudron-setup --provider <digitalocean|ec2|generic|scaleway>
|
|
```
|
|
|
|
The setup will take around 10-15 minutes.
|
|
|
|
**cloudron-setup** takes the following arguments:
|
|
|
|
* `--provider` is the name of your VPS provider. If the name is not on the list, simply
|
|
choose `generic`. In most cases, the `generic` provider mostly will work fine.
|
|
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 for installation:
|
|
|
|
* `--tls-provider` is the name of the SSL/TLS certificate backend. Defaults to Let's encrypt.
|
|
Specifying `fallback` will setup the Cloudron to use the fallback wildcard certificate.
|
|
Initially a self-signed one is provided, which can be overwritten later in the admin interface.
|
|
This may be useful for non-public installations.
|
|
|
|
Optional arguments used for update and restore:
|
|
|
|
* `--version` is the version of Cloudron to install. By default, the setup script installs
|
|
the latest version. You can set this to an older version when restoring a Cloudron from a backup.
|
|
|
|
* `--restore-url` is a backup URL to restore from.
|
|
|
|
## Domain setup
|
|
|
|
Once the setup script completes, the server will reboot, then visit your server by its
|
|
IP address (`https://ip`) to complete the installation.
|
|
|
|
The setup website will show a certificate warning. Accept the self-signed certificate
|
|
and proceed to the domain setup.
|
|
|
|
Currently, only Second Level Domains 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.
|
|
|
|
### Route 53
|
|
|
|
Create root or IAM credentials and choose `Route 53` as the DNS provider.
|
|
|
|
* For root credentials:
|
|
* In AWS Console, under your name in the menu bar, click `Security Credentials`
|
|
* Click on `Access Keys` and create a key pair.
|
|
* For IAM credentials:
|
|
* You can use the following policy to create IAM credentials:
|
|
|
|
```
|
|
{
|
|
"Version": "2012-10-17",
|
|
"Statement": [
|
|
{
|
|
"Effect": "Allow",
|
|
"Action": "route53:*",
|
|
"Resource": [
|
|
"arn:aws:route53:::hostedzone/<hosted zone id>"
|
|
]
|
|
},
|
|
{
|
|
"Effect": "Allow",
|
|
"Action": [
|
|
"route53:ListHostedZones",
|
|
"route53:GetChange"
|
|
],
|
|
"Resource": [
|
|
"*"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Digital Ocean
|
|
|
|
Create an API token with read+write access and choose `Digital Ocean` as the DNS provider.
|
|
|
|
### Other
|
|
|
|
If your domain *does not* use Route 53 or Digital Ocean, setup a wildcard (`*`) DNS `A` record that points to the
|
|
IP of the server created above. If your DNS provider has an API, please open an
|
|
[issue](https://git.cloudron.io/cloudron/box/issues) and we may be able to support it.
|
|
|
|
## Finish Setup
|
|
|
|
Once the domain setup is done, the Cloudron will configure the DNS and get a SSL certificate. It will automatically redirect to `https://my.<domain>`.
|
|
|
|
# Backups
|
|
|
|
The Cloudron creates encrypted backups once a day. Each app is backed up independently and these
|
|
backups have the prefix `app_`. The platform state is backed up independently with the
|
|
prefix `box_`.
|
|
|
|
By default, backups reside in `/var/backups`. Please note that having backups reside in the same
|
|
physical machine as the Cloudron server instance is dangerous and it must be changed to
|
|
an external storage location like `S3` as soon as possible.
|
|
|
|
## Amazon S3
|
|
|
|
Provide S3 backup credentials in the `Settings` page and leave the endpoint field empty.
|
|
|
|
Create a bucket in S3 (You have to have an account at [AWS](https://aws.amazon.com/)). 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.
|
|
|
|
* For root credentials:
|
|
* In AWS Console, under your name in the menu bar, click `Security Credentials`
|
|
* Click on `Access Keys` and create a key pair.
|
|
* For IAM credentials:
|
|
* You can use the following policy to create IAM credentials:
|
|
|
|
```
|
|
{
|
|
"Version": "2012-10-17",
|
|
"Statement": [
|
|
{
|
|
"Effect": "Allow",
|
|
"Action": "s3:*",
|
|
"Resource": [
|
|
"arn:aws:s3:::<your bucket name>",
|
|
"arn:aws:s3:::<your bucket name>/*"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Minio S3
|
|
|
|
[Minio](https://minio.io/) is a distributed object storage server, providing the same API as Amazon S3.
|
|
Since Cloudron supports S3, any API compatible solution should be supported as well, if this is not the case, let us know.
|
|
|
|
Minio can be setup, by following the [installation instructions](https://docs.minio.io/) on any server, which is reachable by the Cloudron.
|
|
Do not setup Minio on the same server as the Cloudron, this will inevitably result in data loss, if backups are stored on the same instance.
|
|
|
|
Once setup, minio will print the necessary information, like login credentials, region and endpoints in its logs.
|
|
|
|
```
|
|
$ ./minio server ./storage
|
|
|
|
Endpoint: http://192.168.10.113:9000 http://127.0.0.1:9000
|
|
AccessKey: GFAWYNJEY7PUSLTHYHT6
|
|
SecretKey: /fEWk66E7GsPnzE1gohqKDovaytLcxhr0tNWnv3U
|
|
Region: us-east-1
|
|
```
|
|
|
|
First create a new bucket for the backups, using the minio commandline tools or the webinterface. The bucket has to have **read and write** permissions.
|
|
|
|
The information to be copied to the Cloudron's backup settings form may look similar to:
|
|
|
|
<img src="/docs/img/minio_backup_config.png" class="shadow"><br/>
|
|
|
|
|
|
# Email
|
|
|
|
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. 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
|
|
down over time. The Cloudron sets up DNS entries for SPF, DKIM, DMARC automatically and
|
|
reputation should be easy to get back.
|
|
|
|
## Checklist
|
|
|
|
* Once your Cloudron is ready, setup a Reverse DNS PTR record to be setup for the `my` subdomain.
|
|
|
|
* 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.<domain>`. Note that some new Digital Ocean accounts have [port 25 blocked](https://www.digitalocean.com/community/questions/port-25-smtp-external-access).
|
|
|
|
* Scaleway - Edit your security group to allow email. You can also set a PTR record on the interface with your
|
|
`my.<domain>`.
|
|
|
|
* Check if your IP is listed in any DNSBL list [here](http://multirbl.valli.org/). In most cases,
|
|
you can apply for removal of your IP by filling out a form at the DNSBL manager site.
|
|
|
|
* When using wildcard or manual DNS backends, you have to setup the DMARC, MX records manually.
|
|
|
|
* Finally, check your spam score at [mail-tester.com](https://www.mail-tester.com/). The Cloudron
|
|
should get 100%, if not please let us know.
|
|
|
|
# CLI Tool
|
|
|
|
The [Cloudron tool](https://git.cloudron.io/cloudron/cloudron-cli) is useful for managing
|
|
a Cloudron. <b class="text-danger">The Cloudron CLI tool has to be installed & run on a Laptop or PC</b>
|
|
|
|
Once installed, you can install, configure, list, backup and restore apps from the command line.
|
|
|
|
## Linux & OS X
|
|
|
|
Installing the CLI tool requires node.js and npm. The CLI tool can be installed using the following command:
|
|
|
|
```
|
|
npm install -g cloudron
|
|
```
|
|
|
|
Depending on your setup, you may need to run this as root.
|
|
|
|
On OS X, it is known to work with the `openssl` package from homebrew.
|
|
|
|
See [#14](https://git.cloudron.io/cloudron/cloudron-cli/issues/14) for more information.
|
|
|
|
## 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.
|
|
|
|
# Updates
|
|
|
|
Apps installed from the Cloudron Store are automatically updated every night.
|
|
|
|
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
|
|
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
|
|
case an update fails, it can be [restored](/references/selfhosting.html#restore).
|
|
|
|
### Upgrade
|
|
|
|
An **upgrade** requires a new OS image. This process involves creating a new server from scratch
|
|
with the latest code and restoring it from the last backup.
|
|
|
|
To upgrade follow these steps closely:
|
|
|
|
* Create a new backup - `cloudron machine backup create`
|
|
|
|
* List the latest backup - `cloudron machine backup list`
|
|
|
|
* Make the backup available for the new cloudron instance:
|
|
|
|
* `S3` - When storing backup ins S3, make the latest box backup public - files starting with `box_` (from v0.94.0) or `backup_`. This can be done from the AWS S3 console as seen here:
|
|
|
|
<img src="/docs/img/aws_backup_public.png" class="shadow haze"><br/>
|
|
|
|
Copy the new public URL of the latest backup for use as the `--restore-url` below.
|
|
|
|
<img src="/docs/img/aws_backup_link.png" class="shadow haze"><br/>
|
|
|
|
* `File system` - When storing backups in `/var/backups`, you have to make the box and the app backups available to the new Cloudron instance's `/var/backups`. This can be achieved in a variety of ways depending on the situation: like scp'ing the backup files to the machine before installation, mounting the external backup hard drive into the new Cloudron's `/var/backup` OR downloading a copy of the backup using `cloudron machine backup download` and uploading them to the new machine. After doing so, pass `file:///var/backups/<path to box backup>` as the `--restore-url` below.
|
|
|
|
* Create a new Cloudron by following the [installing](/references/selfhosting.html#installing) section.
|
|
When running the setup script, pass in the `--encryption-key` and `--restore-url` flags.
|
|
The `--encryption-key` is the backup encryption key. It can be displayed with `cloudron machine info`
|
|
|
|
Similar to the initial installation, a Cloudron upgrade looks like:
|
|
```
|
|
$ ssh root@newserverip
|
|
> wget https://cloudron.io/cloudron-setup
|
|
> chmod +x cloudron-setup
|
|
> ./cloudron-setup --provider <digitalocean|ec2|generic|scaleway> --encryption-key <key> --restore-url <publicS3Url>
|
|
```
|
|
|
|
* Finally, once you see the newest version being displayed in your Cloudron webinterface, you can safely delete the old server instance.
|
|
|
|
# Restore
|
|
|
|
To restore a Cloudron from a specific backup:
|
|
|
|
* Select the backup - `cloudron machine backup list`
|
|
|
|
* Make the backup public
|
|
|
|
* `S3` - Make the box backup publicly readable - files starting with `box_` (from v0.94.0) or `backup_`. This can be done from the AWS S3 console. Once the box has restored, you can make it private again.
|
|
|
|
* `File system` - When storing backups in `/var/backups`, you have to make the box and the app backups available to the new Cloudron instance's `/var/backups`. This can be achieved in a variety of ways depending on the situation: like scp'ing the backup files to the new machine before Cloudron installation OR mounting an external backup hard drive into the new Cloudron's `/var/backup` OR downloading a copy of the backup using `cloudron machine backup download` and uploading them to the new machine. After doing so, pass `file:///var/backups/<path to box backup>` as the `--restore-url` below.
|
|
|
|
* Create a new Cloudron by following the [installing](/references/selfhosting.html#installing) section.
|
|
When running the setup script, pass in the `version`, `encryption-key` and `restore-url` flags.
|
|
The `version` field is the version of the Cloudron that the backup corresponds to (it is embedded
|
|
in the backup file name).
|
|
|
|
* Make the box backup private, once the upgrade is complete.
|
|
|
|
# Debug
|
|
|
|
You can SSH into your Cloudron and collect logs:
|
|
|
|
* `journalctl -a -u box` 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`,
|
|
`mysql` etc. If you want to get a specific container's log output, `journalctl -a CONTAINER_ID=<container_id>`.
|
|
|
|
# Alerts
|
|
|
|
The Cloudron will notify the Cloudron administrator via email if apps go down, run out of memory, have updates
|
|
available etc.
|
|
|
|
You will have to setup a 3rd party service like [Cloud Watch](https://aws.amazon.com/cloudwatch/) or [UptimeRobot](http://uptimerobot.com/) to monitor the Cloudron itself. You can use `https://my.<domain>/api/v1/cloudron/status`
|
|
as the health check URL.
|
|
|
|
# Help
|
|
|
|
If you run into any problems, join us at our [chat](https://chat.cloudron.io) or [email us](mailto:support@cloudron.io).
|