diff --git a/docs/references/addons.md b/docs/references/addons.md index 2503f25bb..fdb93afe7 100644 --- a/docs/references/addons.md +++ b/docs/references/addons.md @@ -1,6 +1,4 @@ -# Addons - -## Overview +# Overview Addons are services like database, authentication, email, caching that are part of the Cloudron runtime. Setup, provisioning, scaling and maintanence of addons is taken care of @@ -10,7 +8,7 @@ The fundamental idea behind addons is to allow sharing of Cloudron resources acr For example, a single MySQL server instance can be used across multiple apps. The Cloudron runtime sets up addons in such a way that apps are isolated from each other. -## Using Addons +# Using Addons Addons are opt-in and must be specified in the [Cloudron Manifest](/references/manifest.html). When the app runs, environment variables contain the necessary information to access the addon. @@ -36,9 +34,9 @@ for this purpose to setup and update the DB schema. } ``` -## All addons +# All addons -### email +## email This addon allows an app to send and recieve emails on behalf of the user. The intended use case is webmail applications. @@ -60,7 +58,7 @@ MAIL_SIEVE_PORT= # ManageSieve server port MAIL_DOMAIN= # Domain of the mail server ``` -### ldap +## ldap This addon provides LDAP based authentication via LDAP version 3. @@ -92,7 +90,7 @@ cloudron exec > ldapsearch -x -h "${LDAP_SERVER}" -p "${LDAP_PORT}" -b "${LDAP_GROUPS_BASE_DN}" ``` -### localstorage +## localstorage Since all Cloudron apps run within a read-only filesystem, this addon provides a writeable folder under `/app/data/`. All contents in that folder are included in the backup. On first run, this folder will be empty. File added in this path @@ -107,7 +105,7 @@ If the app is running under the recommeneded `cloudron` user, this can be achiev chown -R cloudron:cloudron /app/data ``` -### mongodb +## mongodb By default, this addon provide mongodb 2.6.3. @@ -128,7 +126,7 @@ cloudron exec # mongo -u "${MONGODB_USERNAME}" -p "${MONGODB_PASSWORD}" ${MONGODB_HOST}:${MONGODB_PORT}/${MONGODB_DATABASE} ``` -### mysql +## mysql By default, this addon provides a single database on MySQL 5.6.19. The database is already created and the application only needs to create the tables. @@ -158,7 +156,7 @@ the following environment variables are injected: MYSQL_DATABASE_PREFIX= # prefix to use to create databases ``` -### oauth +## oauth The Cloudron OAuth 2.0 provider can be used in an app to implement Single Sign-On. @@ -188,7 +186,7 @@ is so that apps cannot make undesired changes to the user's Cloudron. We currently provide OAuth2 integration for Ruby [omniauth](https://github.com/cloudron-io/omniauth-cloudron) and Node.js [passport](https://github.com/cloudron-io/passport-cloudron). -### postgresql +## postgresql By default, this addon provides PostgreSQL 9.4.4. @@ -211,7 +209,7 @@ cloudron exec > PGPASSWORD=${POSTGRESQL_PASSWORD} psql -h ${POSTGRESQL_HOST} -p ${POSTGRESQL_PORT} -U ${POSTGRESQL_USERNAME} -d ${POSTGRESQL_DATABASE} ``` -### recvmail +## recvmail The recvmail addon can be used to receive email for the application. @@ -237,7 +235,7 @@ cloudron exec The IMAP command `? LOGIN username password` can then be used to test the authentication. -### redis +## redis By default, this addon provides redis 2.8.13. The redis is configured to be persistent and data is preserved across updates and restarts. @@ -257,7 +255,7 @@ cloudron exec > redis-cli -h "${REDIS_HOST}" -p "${REDIS_PORT}" -a "${REDIS_PASSWORD}" ``` -### scheduler +## scheduler The scheduler addon can be used to run tasks at periodic intervals (cron). @@ -297,7 +295,7 @@ If a task is still running when a new instance of the task is scheduled to be st task instance is killed. -### sendmail +## sendmail The sendmail addon can be used to send email from the application. @@ -320,7 +318,7 @@ cloudron exec > swaks --server "${MAIL_SMTP_SERVER}" -p "${MAIL_SMTP_PORT}" --from "${MAIL_SMTP_USERNAME}@${MAIL_DOMAIN}" --body "Test mail from cloudron app at $(hostname -f)" --auth-user "${MAIL_SMTP_USERNAME}" --auth-password "${MAIL_SMTP_PASSWORD}" ``` -### simpleauth +## simpleauth Simple Auth can be used for authenticating users with a HTTP request. This method of authentication is targeted at applications, which for whatever reason can't use the ldap addon. diff --git a/docs/references/architecture.md b/docs/references/architecture.md index e39f669b4..f5d9b2306 100644 --- a/docs/references/architecture.md +++ b/docs/references/architecture.md @@ -1,6 +1,4 @@ -# Architecture - -## Introduction +# Introduction The Cloudron platform is designed to easily install and run web applications. The application architecture is designed to let the Cloudron take care of system @@ -17,7 +15,7 @@ Web applications like blogs, wikis, password managers, code hosting, document ed file syncers, notes, email, forums are a natural fit for the Cloudron. Decentralized "social" networks are also good app candidates for the Cloudron. -## Image +# Image Application images are created using [Docker](https://www.docker.io). Docker provides a way to package (and containerize) the application as a filesystem which contains it's code, system libraries @@ -34,7 +32,7 @@ and packages that are independent of the host OS. The [base image](/references/baseimage.html) is the parent of all app images. -## Cloudron Manifest +# Cloudron Manifest Each app provides a `CloudronManifest.json` that specifies information required for the `Cloudron Store` and for the installation of the image in the Cloudron. @@ -53,7 +51,7 @@ Information required for the Cloudron Store includes: See the [manifest reference](/references/manifest.html) for more information. -## Addons +# Addons Addons are services like database, authentication, email, caching that are part of the Cloudron. Setup, provisioning, scaling and maintenance of addons is taken care of by the @@ -67,7 +65,7 @@ Addons are opt-in and must be specified in the Cloudron Manifest. When the app r variables contain the necessary information to access the addon. See the [addon reference](/references/addons.html) for more information. -## Authentication +# Authentication The Cloudron provides a centralized dashboard to manage users, roles and permissions. Applications do not create or manage user credentials on their own and instead use one of the various @@ -79,12 +77,12 @@ Authentication strategies include OAuth 2.0, LDAP or Simple Auth. See the Authorizing users is application specific and it is only authentication that is delegated to the Cloudron. -## Cloudron Store +# Cloudron Store Cloudron Store provides a market place to publish and optionally monetize your app. Submitting to the Cloudron Store enables any Cloudron user to discover, purchase and install your application with a few clicks. -## What next? +# What next? * [Package an existing app for the Cloudron](/tutorials/packaging.html) \ No newline at end of file diff --git a/docs/references/authentication.md b/docs/references/authentication.md index 5eade221a..7ed6f27e1 100644 --- a/docs/references/authentication.md +++ b/docs/references/authentication.md @@ -1,6 +1,4 @@ -# Authentication - -## Overview +# Overview Cloudron provides a centralized dashboard to manage users, roles and permissions. Applications do not create or manage user credentials on their own and instead use one of the various @@ -10,7 +8,7 @@ Note that authentication only identifies a user and does not indicate if the use to perform an action in the application. Authorizing users is application specific and must be implemented by the application. -## Users & Admins +# Users & Admins Cloudron user management is intentionally very simple. The owner (first user) of the Cloudron is `admin` by default. The `admin` role allows one to install, uninstall and reconfigure @@ -25,7 +23,7 @@ A Cloudron `admin` can give admin privileges to one or more Cloudron users. Each Cloudron user has an unique `username` and an `email`. -## Strategies +# Strategies Cloudron provides multiple authentication strategies. @@ -33,7 +31,7 @@ Cloudron provides multiple authentication strategies. * LDAP provided by the [LDAP addon](/references/addons.html#ldap) * Simple Auth provided by [Simple Auth addon](/references/addons.html#simpleauth) -## Choosing a strategy +# Choosing a strategy Applications can be broadly categorized based on their user management as follows: @@ -60,7 +58,7 @@ Applications can be broadly categorized based on their user management as follow * Such apps _must_ set the `singleUser` property in the manifest which will restrict login to a single user (configurable through the Cloudron's admin panel). -## Public and Private apps +# Public and Private apps `Private` apps display content only when they have a signed-in user. These apps can choose one of the authentication strategies listed above. @@ -77,7 +75,7 @@ from a settings ui in the app, it's better to simply put some sensible defaults the settings. In the case where such settings cannot be changed dynamically, it is best to simply publish two separate apps in the Cloudron store each with a different configuration. -## External User Registration +# External User Registration Some apps allow external users to register and create accounts. For example, a public company chat that can invite anyone to join or a blog allowing registered commenters. @@ -92,14 +90,14 @@ Naively handling user registration enables attacks of the following kind: * When a user named `foo` logs in, the app cannot determine the correct `foo` anymore. Making separate login buttons for each login source clears the confusion for both the user and the app. -## Userid +# Userid The preferred approach to track users in an application is a uuid or the Cloudron `username`. The `username` in Cloudron is unique and cannot be changed. Tracking users using `email` field is error prone since that may be changed by the user anytime. -## Single Sign-on +# Single Sign-on Single sign-on (SSO) is a property where a user logged in one application automatically logs into another application without having to re-enter his credentials. When applications implement the @@ -108,7 +106,7 @@ OAuth, they will automatically log into any other app implementing OAuth. Conversely, signing off from one app, logs them off from all the apps. -## Security +# Security The LDAP and Simple Auth strategies require the user to provide their plain text passwords to the application. This might be a cause of concern and app developers are thus highly encouraged to integrate diff --git a/docs/references/baseimage.md b/docs/references/baseimage.md index 20b7021d3..564a56855 100644 --- a/docs/references/baseimage.md +++ b/docs/references/baseimage.md @@ -1,6 +1,4 @@ -# Base Image - -## Overview +# Overview The application's Dockerfile must specify the FROM base image to be `cloudron/base:0.9.0`. @@ -12,7 +10,7 @@ are not configured in any way and it's up to the application to configure them a For example, while `apache` is installed, there are no meaningful site configurations that the application can use. -## Packages +# Packages The following packages are part of the base image. If you need another version, you will have to install it yourself. @@ -37,7 +35,7 @@ install it yourself. * Supervisor 3.2.0 * uwsgi 2.0.12 -## Inspecting the base image +# Inspecting the base image The base image can be inspected by installing [Docker](https://docs.docker.com/installation/). @@ -54,40 +52,40 @@ To inspect the base image: *Note:* Please use `docker 1.9.0` or above to pull the base image. Doing otherwise results in a base image with an incorrect image id. The image id of `cloudron/base:0.9.0` is `d038af182821`. -## The `cloudron` user +# The `cloudron` user The base image contains a user named `cloudron` that apps can use to run their app. It is good security practice to run apps as a non-previleged user. -## Env vars +# Env vars The following environment variables are set as part of the application runtime. -### API_ORIGIN +## API_ORIGIN API_ORIGIN is set to the HTTP(S) origin of this Cloudron's API. For example, `https://my-girish.cloudron.us`. -### APP_DOMAIN +## APP_DOMAIN APP_DOMAIN is set to the domain name of the application. For example, `app-girish.cloudron.us`. -### APP_ORIGIN +## APP_ORIGIN APP_ORIGIN is set to the HTTP(S) origin on the application. This is origin which the user can use to reach the application. For example, `https://app-girish.cloudron.us`. -### CLOUDRON +## CLOUDRON CLOUDRON is always set to '1'. This is useful to write Cloudron specific code. -### WEBADMIN_ORIGIN +## WEBADMIN_ORIGIN WEBADMIN_ORIGIN is set to the HTTP(S) origin of the Cloudron's web admin. For example, `https://my-girish.cloudron.us`. -## Node.js +# Node.js The base image comes pre-installed with various node.js versions. diff --git a/docs/references/manifest.md b/docs/references/manifest.md index 635ec7120..6ce1ef16a 100644 --- a/docs/references/manifest.md +++ b/docs/references/manifest.md @@ -1,6 +1,4 @@ -# CloudronManifest - -## Overview +# Overview Every Cloudron Application contains a `CloudronManifest.json`. @@ -40,9 +38,9 @@ Here is an example manifest: } ``` -## Fields +# Fields -### addons +## addons Type: object @@ -68,7 +66,7 @@ Example: } ``` -### author +## author Type: string @@ -81,7 +79,7 @@ Example: "author": "Cloudron Inc " ``` -### changelog +## changelog Type: markdown string @@ -95,7 +93,7 @@ Example: "changelog": "* Add support for IE8 \n* New logo" ``` -### configurePath +## configurePath Type: path string @@ -115,7 +113,7 @@ Example: "configurePath": "/wp-admin" ``` -### contactEmail +## contactEmail Type: email @@ -129,7 +127,7 @@ Example: "contactEmail": "support@testapp.com" ``` -### customAuth +## customAuth Type: boolean @@ -146,7 +144,7 @@ Example: "customAuth": true ``` -### description +## description Type: markdown string @@ -169,7 +167,7 @@ Example: "description:": "file://DESCRIPTION.md" ``` -### developmentMode +## developmentMode Type: boolean @@ -183,7 +181,7 @@ This mode can be used to identify the files being modified by your application - debug situations where your app does not run on a readonly rootfs. Run your app using `cloudron exec` and use `find / -mmin -30` to find file that have been changed or created in the last 30 minutes. -### healthCheckPath +## healthCheckPath Type: url path @@ -199,7 +197,7 @@ Example: ``` "healthCheckPath": "/" ``` -### httpPort +## httpPort Type: positive integer @@ -220,7 +218,7 @@ Example: "httpPort": 8080 ``` -### icon +## icon Type: local image filename @@ -233,7 +231,7 @@ to be square of size 256x256. "icon": "file://icon.png" ``` -### id +## id Type: reverse domain string @@ -249,7 +247,7 @@ the application if the id is already in use by another application. "id": "io.cloudron.testapp" ``` -### manifestVersion +## manifestVersion Type: integer @@ -261,7 +259,7 @@ Required: yes "manifestVersion": 1 ``` -### mediaLinks +## mediaLinks Type: array of urls @@ -279,7 +277,7 @@ All links are preferably https. ] ``` -### memoryLimit +## memoryLimit Type: bytes (integer) @@ -294,7 +292,7 @@ By default, all apps have a memoryLimit of 256MB. For example, to have a limit o "memoryLimit": 524288000 ``` -### maxBoxVersion +## maxBoxVersion Type: semver string @@ -306,7 +304,7 @@ a box greater than `maxBoxVersion` will fail. This is useful when a new box release introduces features which are incompatible with the app. This situation is quite unlikely and it is recommended to leave this unset. -### minBoxVersion +## minBoxVersion Type: semver string @@ -318,7 +316,7 @@ a box lesser than `minBoxVersion` will fail. This is useful when the app relies on features that are only available from a certain version of the box. If unset, the default value is `0.0.1`. -### postInstallMessage +## postInstallMessage Type: markdown string @@ -330,7 +328,7 @@ The intended use of this field is to display some post installation steps that t complete the installation. For example, displaying the default admin credentials and informing the user to to change it. -### singleUser +## singleUser Type: boolean @@ -341,7 +339,7 @@ The `singleUser` field can be set to true for apps that are meant to be used onl When set, the Cloudron will display a user selection dialog at installation time. The selected user is the sole user who can access the app. -### tagline +## tagline Type: one-line string @@ -353,7 +351,7 @@ The `tagline` is used by the Cloudron Store to display a single line short descr "tagline": "The very best note keeper" ``` -### tags +## tags Type: Array of strings @@ -365,7 +363,7 @@ The `tags` are used by the Cloudron Store for filtering searches by keyword. "tags": [ "git", "version control", "scm" ] ``` -### targetBoxVersion +## targetBoxVersion Type: semver string @@ -381,7 +379,7 @@ and will disable the SELinux feature for the app. If unspecified, this value defaults to `minBoxVersion`. -### tcpPorts +## tcpPorts Type: object @@ -446,7 +444,7 @@ In more detail: it might be simpler to listen on `SSH_PORT` internally. In such cases, the app can omit the `containerPort` value and should instead reconfigure itself to listen internally on `SSH_PORT` on each start up. -### title +## title Type: string @@ -459,7 +457,7 @@ Example: "title": "Gitlab" ``` -### version +## version Type: semver string @@ -473,7 +471,7 @@ Example: "version": "1.1.0" ``` -### website +## website Type: url diff --git a/docs/references/selfhosting.md b/docs/references/selfhosting.md index a236acc42..96cb7363b 100644 --- a/docs/references/selfhosting.md +++ b/docs/references/selfhosting.md @@ -1,10 +1,10 @@ -# Self host Cloudron +# Overview The Cloudron platform can be installed on your own cloud server. The self hosted version comes with all the same features as the managed version. If you have any questions, join us at our [chat](https://chat.cloudron.io). -## CLI Tool +# CLI Tool The [Cloudron tool](https://git.cloudron.io/cloudron/cloudron-cli) is used for managing a Cloudron. It has a `machine` subcommand that can be used to create, update and maintain a self-hosted Cloudron. @@ -13,7 +13,7 @@ subcommand that can be used to create, update and maintain a self-hosted Cloudro The Cloudron CLI tool has to be run on a Laptop or PC, not on the cloud server!
-### Linux & OS X +## Linux & OS X Installing the CLI tool requires node.js and npm. The CLI tool can be installed using the following command: ``` @@ -26,11 +26,11 @@ 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 +## Windows The CLI tool does not work on Windows. -### Machine subcommands +## Machine subcommands You should now be able to run the `cloudron machine help` command in a shell. @@ -45,9 +45,9 @@ ssh Get remote SSH connection backup Manage Cloudron backups ``` -## AWS EC2 +# AWS EC2 -### Requirements +## Requirements To run the Cloudron on AWS, first sign up with [Amazon AWS](https://aws.amazon.com/). @@ -63,7 +63,7 @@ The Cloudron runs best on instances which do not have a burst mode VCPU. The system disk space usage of a Cloudron is around 15GB. This results in a minimum requirement of about 30GB to give some headroom for app installations and user data. -### Cost Estimation +## Cost Estimation Taking the minimal requirements of hosting on EC2, with a backup retention of 2 days, the cost estimation per month is as follows: @@ -78,7 +78,7 @@ Total: $ 24.75/mth For custom cost estimation, please use the [AWS Cost Calculator](http://calculator.s3.amazonaws.com/index.html) -### Setup +## Setup Open the AWS console and create the required resources: @@ -154,7 +154,7 @@ The supported regions are: } ``` -### Create the Cloudron +## Create the Cloudron Create the Cloudron using the `cloudron machine` command: @@ -186,10 +186,10 @@ around the `secret` to prevent accidental shell expansion. **NOTE**: See `cloudron machine create ec2 --help` for all available options. -## DigitalOcean +# DigitalOcean -### Requirements +## Requirements To run the Cloudron on DigitalOcean, first sign up with [DigitalOcean](https://m.do.co/c/933831d60a1e) (Use this referral link to get $10 credit). @@ -198,7 +198,7 @@ The minimum requirements for a Cloudron depends on the apps installed. The absol All backups on DigitalOcean Cloudrons are stored locally at `/var/backups`. We recommend to download backups from time to time to a different location using `cloudron machine backup download`. -### Setup +## Setup Open the DigitalOcean console and do the following: @@ -213,7 +213,7 @@ Open the DigitalOcean console and do the following: * Click on the domain you created and delete the '@' dummy record created above. -### Create the Cloudron +## Create the Cloudron Create the Cloudron using the `cloudron machine` command: @@ -239,7 +239,7 @@ around the `secret` to prevent accidental shell expansion. **NOTE**: See `cloudron machine create digitalocean --help` for all available options. -## First time setup +# First time setup Visit `https://my.` to do first time setup of your Cloudron. @@ -251,7 +251,7 @@ already! In this unlikely case, simply delete the instance and create a new Clou Once the setup is done, you can access the admin page in the future at `https://my.`. -## Backups +# Backups The Cloudron has a backup schedule of creating one once a day. In addition to regularly scheduled backups, a backup is also created if you update the Cloudron or any of the apps (in this case only the app in question will get backed up). @@ -272,7 +272,7 @@ cloudron machine backup list --provider ec2 \ ``` -## Restore +# Restore The Cloudron can restore itself from a backup using the following command: ``` @@ -291,7 +291,7 @@ cloudron machine create ec2 \ The backup id can be obtained by [listing the backup](/references/selfhosting.html#backups). Other arguments are similar to [Cloudron creation](/references/selfhosting.html#create-the-cloudron). Once the new instance has completely restored, you can safely terminate the old Cloudron from the AWS console. -## Updates +# Updates Apps installed from the Cloudron Store are updated automatically every night. @@ -307,7 +307,7 @@ Once the upgrade is complete, you can safely terminate the old EC2 instance. The Cloudron will always make a complete backup before attempting an update or upgrade. In the unlikely case an update fails, it can be [restored](/references/selfhosting.html#restore). -## SSH +# SSH If you want to SSH into your Cloudron, you can ``` @@ -319,14 +319,14 @@ If you are unable to connect, verify the following: * The SSH Key should be in PEM format. If you are using Putty PPK files, follow [this article](http://stackoverflow.com/questions/2224066/how-to-convert-ssh-keypairs-generated-using-puttygenwindows-into-key-pairs-use) to convert it to PEM format. * The SSH Key must have correct permissions (400) set (this is a requirement of the ssh client). -## Mail +# Mail 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 +## Checklist * Once your Cloudron is ready, setup a Reverse DNS PTR record to be setup for the `my` subdomain. @@ -341,7 +341,7 @@ of your IP by filling out a form at the DNSBL manager site. * 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. -## Debugging +# Debugging To debug the Cloudron CLI tool: @@ -353,7 +353,7 @@ You can also [SSH](#ssh) into your Cloudron and collect logs. * `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 containers log output, `journalctl -a CONTAINER_ID=`. -## Hotfixing +# Hotfixing Hotfixing is the process of patching your Cloudron to run the latest git code. This is useful if require a patch urgently and for testing and development. Note that it is ot possible to hotfix between arbitrary git revisions (for example, if there is some db migration involved), so use this with care. @@ -364,11 +364,11 @@ To hotfix your cloudron, run the following from the `box` code checkout: cloudron machine hotfix --ssh-key ``` -## Other Providers +# Other Providers Currently, we do not support other cloud server provider. Please let us know at [support@cloudron.io](mailto:support@cloudron.io), if you want to see other providers supported. -## Help +# Help If you run into any problems, join us in our [chat](https://chat.cloudron.io) or [email us](mailto:support@cloudron.io). diff --git a/docs/references/usermanual.md b/docs/references/usermanual.md index 18340aaaf..94cb8b2c5 100644 --- a/docs/references/usermanual.md +++ b/docs/references/usermanual.md @@ -1,6 +1,4 @@ -# User Manual - -## Introduction +# Introduction The Cloudron is the best platform self-hosting web applications on your server. You can easily install apps on it, add users, manage access restriction and keep your @@ -27,7 +25,7 @@ completely automated. If you want to learn more about the secret sauce that makes the Cloudron, please read our [architecture overview](/references/architecture.html). -## Use cases +# Use cases Here are some of the apps you can run on a Cloudron: @@ -41,7 +39,7 @@ Here are some of the apps you can run on a Cloudron: Our list of apps is growing everyday, so be sure to [follow us on twitter](https://twitter.com/cloudron_io). -## Activation +# Activation When you first create the Cloudron, the setup wizard will ask you to setup an administrator account. Don't worry, a Cloudron adminstrator doesn't need to know anything about maintaining @@ -54,9 +52,9 @@ the Cloudron from the `Users` menu item. The Cloudron administration page is located at the `my` subdomain. You might want to bookmark this link! -## Apps +# Apps -### Installation +## Installation You can install apps on the Cloudron by choosing the `App Store` menu item. Use the 'Search' bar to search for apps. @@ -85,7 +83,7 @@ visit the Cloudron administration panel. * `Restrict to groups` - Only users in the groups can access the app. -### Updates +## Updates All your apps automatically update as and when the application author releases an update. The Cloudron will attempt to update around midnight of your timezone. @@ -96,7 +94,7 @@ of clicking the `Update` button (the green star) after you read about the change -### Backups +## Backups If you self-host, please refer to the [self-hosting documentation](/references/selfhosting.html#backups) for backups. @@ -104,7 +102,7 @@ All apps are automatically backed up every day. Backups are stored encrypted in to do anything about it. The [Cloudron CLI](https://git.cloudron.io/cloudron/cloudron-cli) tool can be used to download application backups. -### Configuration +## Configuration Apps can be reconfigured using the `Configure` button. @@ -120,7 +118,7 @@ You can do the following: Changing an app's configuration has a small downtime (usually around a minute). -### Restore +## Restore Apps can be restored to a previous backup by clicking on the `Restore` button. @@ -130,7 +128,7 @@ Note that restoring previous data might also restore the previous version of the be currently using Version 5 of the app. If you restore to a backup that was made with Version 3 of the app, then the restore operation will install Version 3 of the app. This is because the latest version may not be able to handle old data. -### Uninstall +## Uninstall You can uninstall an app by clicking the `Uninstall` button. @@ -140,7 +138,7 @@ Note that all data associated with the app will be immediately removed from the persist in your old backups and the [CLI tool](https://git.cloudron.io/cloudron/cloudron-cli) provides a way to restore from those old backups should it be required. -### Embedding Apps +## Embedding Apps It is possible to embed Cloudron apps into other websites. By default, this is disabled to prevent [Clickjacking](https://cloudron.io/blog/2016-07-15-site-embedding.html). @@ -148,14 +146,14 @@ It is possible to embed Cloudron apps into other websites. By default, this is d You can set a website that is allowed to embed your Cloudron app using the app's [Configure dialog](#configuration). Click on 'Show Advanced Settings...' and enter the embedder website name. -## Custom domain +# Custom domain When you create a Cloudron from cloudron.io, we provide a subdomain under `cloudron.me` like `girish.cloudron.me`. Apps are available under that subdomain using a hyphenated name like `blog-girish.cloudron.me`. Domain names are a thing of pride and the Cloudron makes it easy to make your apps accessible from memorable locations like `blog.girish.in`. -### Single app on a custom domain +## Single app on a custom domain This approach is applicable if you desire that only a single app be accessing from a custom domain. For this, open the app's configure dialog and choose `External Domain` in the location dropdown. @@ -165,7 +163,7 @@ domain. For this, open the app's configure dialog and choose `External Domain` i This dialog will suggest you to add a `CNAME` record. Once you setup a CNAME record with your DNS provider, the app will be accessible from that external domain. -### Entire Cloudron on a custom domain +## Entire Cloudron on a custom domain This approach is applicable if you want all your apps to be accessible from subdomains of your custom domain. For example, `blog.girish.in`, `notes.girish.in`, `owncloud.girish.in`, `mail.girish.in` and so on. This @@ -182,9 +180,9 @@ Change the domain name to your custom domain. Currently, we require that your do Moving to a custom domain will retain all your apps and data and will take around 15 minutes. If you require assistance with another provider, just let us know. -## User management +# User management -### Users +## Users You can invite new users (friends, family, colleagues) with their email address from the `Users` menu. They will receive an invite to sign up with your Cloudron. They can now access the apps that you have given them access @@ -194,7 +192,7 @@ to. To remove a user, simply remove them from the list. Note that the removed user cannot access any app anymore. -### Administrators +## Administrators A Cloudron administrator is a special right given to an existing Cloudron user allowing them to manage apps and users. To make an existing user an administator, click the edit (pencil) button corresponding to @@ -202,7 +200,7 @@ the user and check the `Allow this user to manage apps, groups and other users` -### Groups +## Groups Groups provide a convenient way to group users. It's purpose is two-fold: @@ -219,19 +217,19 @@ To set the access restriction use the app's configure dialog. You can now send mails to `groupname@` to address all the group members. -## Login +# Login -### Cloudron admin +## Cloudron admin The Cloudron admin page is always located at the `my` subdomain of your Cloudron domain. For custom domains, this will be like `my.girish.in`. For domains from cloudron.io, this will be like `my-girish.cloudron.me`. -### Apps (single sign-on) +## Apps (single sign-on) An important feature of the Cloudron is Single Sign-On. You use the same username & password for logging in to all your apps. No more having to manage separate set of credentials for each service! -### Single user apps +## Single user apps Some apps only work with a single user. For example, a notes app might allow only a single user to login and add notes. For such apps, you will be prompted during installation to select the single user who can access the app. @@ -240,13 +238,13 @@ notes. For such apps, you will be prompted during installation to select the sin If you want multiple users to use the app independently, simply install the app multiple times to different locations. -## Email +# Email The Cloudron has a built-in email server. The primary email address is the same as the username. Emails can be sent and received from `@`. The Cloudron does not allow masquerading - one user cannot send email pretending to be another user. -### Enabling Email +## Enabling Email By default, Cloudron's email server only allows apps to send email. To enable users to send and receive email, turn on the option under `Settings`. Turning on this option also allows apps to _receive_ email. @@ -255,7 +253,7 @@ Once email is enabled, the Cloudron will keep the the `MX` DNS record updated. -### Receiving email using IMAP +## Receiving email using IMAP Use the following settings to receive email. @@ -264,7 +262,7 @@ Use the following settings to receive email. * Connection Security - TLS * Username/password - Same as your Cloudron credentials -### Sending email using SMTP +## Sending email using SMTP Use the following settings to send email. @@ -273,7 +271,7 @@ Use the following settings to send email. * Connection Security - STARTTLS * Username/password - Same as your Cloudron credentials -### Email filters using Sieve +## Email filters using Sieve Use the following settings to setup email filtering users via Manage Sieve. @@ -285,7 +283,7 @@ Use the following settings to setup email filtering users via Manage Sieve. The [Rainloop](https://cloudron.io/appstore.html?app=net.rainloop.cloudronapp) and [Roundcube](https://cloudron.io/appstore.html?app=net.roundcube.cloudronapp) apps are already pre-configured to use the above settings. -### Aliases +## Aliases You can configure one or more aliases alongside the primary email address of each user. You can set aliases by editing the user's settings, available behind the edit button in the user listing. Note that aliases cannot conflict with existing user names. @@ -295,22 +293,22 @@ user's settings, available behind the edit button in the user listing. Note that Currently, it is not possible to login using the alias for SMTP/IMAP/Sieve services. Instead, add the alias as an identity in your mail client but login using the Cloudron credentials. -### Subaddresses +## Subaddresses Emails addressed to `+tag@` will be delivered to the `username` mailbox. You can use this feature to give out emails of the form `username+kayak@`, `username+aws@` and so on and have them all delivered to your mailbox. -### Forwarding addresses +## Forwarding addresses Each group on the Cloudron is also a forwarding address. Mails can be addressed to `group@` and the mail will be sent to each user who is part of the group. -### Marking Spam +## Marking Spam The spam detection agent on the Cloudron requires training to identify spam. To do this, simply move your junk mails to a pre-created folder named `Spam`. Most mail clients have a Junk or Spam button which does this automatically. -## Graphs +# Graphs The Graphs view shows an overview of the disk and memory usage on your Cloudron. @@ -325,32 +323,32 @@ on the graph to see the memory consumption over time in the chart below it. The `System` Memory graph shows the overall memory consumption on the entire Cloudron. If you see the Free memory < 50MB frequently, you should consider upgrading to a Cloudron with more memory. -## Activity log +# Activity log The `Activity` view shows the activity on your Cloudron. It includes information about who is using the apps on your Cloudron and also tracks configuration changes. -## Domains and SSL Certificates +# Domains and SSL Certificates All apps on the Cloudron can only be reached by `https`. The Cloudron automatically installs and renews certificates for your apps as needed. Should installation of certificate fail for reasons beyond it's control, Cloudron admins will get a notification about it. -## API Access +# API Access All the operations listed in this manual like installing app, configuring users and groups, are completely programmable with a [REST API](/references/api.html). -## Moving to a larger Cloudron +# Moving to a larger Cloudron When using a Cloudron from cloudron.io, it is easy to migrate your apps and data to a bigger server. In the `Settings` page, you can change the plan. -## Command line tool +# Command line tool If you are a software developer or a sysadmin, the Cloudron comes with a CLI tool that can be used to develop custom apps for the Cloudron. Read more about it [here](https://git.cloudron.io/cloudron/cloudron-cli).