Documentation

Didn't know where to start? Here we have something might be useful.

Web Application

Overview

The web application is a website that can be managed by can adding, editing, or deleting.

Each web app is separate each from each other. Most people who come from cPanel tend to put everything inside a folder and then serve it to the public. Similarly, each web app is separated into its own folder, with its own database and permissions, sandboxed, and served to the public.

Sandboxing each web app allows it to be secure and protected in its own right. If one of your websites is compromised, the others would be completely safe.

With Web Application, you have to treat a website as one application. Yes can still put everything under one folder, but only do that if you have no other choices.

Why we are asking you to separate them? First of all, look at your apps inside your phone. Can you find other app inside your app? None right? Every app is separated from another app because each app contains their own settings, their own database and their own permissions.

Let see from another perspective, how about you put WordPress inside another WordPress. For example, you have installed WordPress inside http://example.com (WordPress A) and you put another WordPress inside http://example.com/blog
(Wordpress B). We are not saying this is wrong, you can still achieve this with Web Application but WordPress B is now a part of WordPress A. We don’t think this is what you want. What you want is WordPress B is separated from WordPress A, but configuration like that is just a plain wrong. If you are using vulnerable plugins inside WordPress A or WordPress B. It is safe to say, both WordPress already compromised.

With Web Application, each of your website will have their own settings. If one of your Web Application was hacked, the hacker won’t be able to compromised other website inside your server unless you have changed our default configuration blindly.

Creating web application

Creating Web Application is easier than you can imagine. First of all, click the create button and you will see the form to create your Web Application.

Form Field Justification
Web Application Name Name of your website or any name you choose.
Domain Name The domain or subdomain name to access to your website. Your domain does not have to be active to set up a server. You may use the IP address of your server for access once you set the web application as the Default Web Application.
User Create a user associated with the website. Every file inside the web application will belong only to this user.
Public Path This is where your visitors can see your website. By default, index.php will usually be the default file in the folder that is publicly seen on the web. For most web applications, you can leave this blank. If your are using custom hand made web application such as Laravel, this will point to /path/to/root/web/application/public
PHP Version You can run your website with any PHP version that you want. If your web application breaks at PHP7.0, PHP 7.1 or PHP7.2, you can revert to an older version such as PHP5.5 or PHP5.6.
Web Application Stack There are two stack that you can choose from here.

1. NGINX + Apache2 Hybrid Stack:

NGINX works as reverse proxy for Apache2. Different from most setup, this stack doesn't fully proxying Apache2. NGINX is really best at serving static content. By using this stack, your static files (eg: css,js,images,fonts) will be served by NGINX. If it is PHP, NGINX will pass it to Apache2 and the request will be pass to PHP-FPM. This setup is great if you are leveraging on .htaccess.

2. Native NGINX Stack:

Your sites will be fully controlled by NGINX. If it is PHP files, NGINX will pass it to FastCGI to communicate with PHP-FPM. This stack doesn't support .htaccess. If you are going to do rewrite or including your own config, you can extend NGINX config by following this example.

3. Native NGINX + Custom config Stack:

Your sites will be fully controlled by NGINX. This stack will not serve your PHP file. You have to manually extend the config by following this example. This is suitable if you want to run nodejs/python/golang/websocket/ror/etc.

Stack Mode There are two stack mode that you can choose from here.

1. Production

This will instruct visitor to your web application to cache static files (js/css/fonts/images/html) inside their browser.

2. Development

This will prevent the browser from caching your static files (js/css/fonts/images/html). Development mode does not prevent from other caching method such as Redis, Memcached or in-app caching.

Advance Setting Please take a look at Web Application Settings section.

After you have created a web application, we will send a signal to your server to create your web which will enabled you to provision further changes.

Default web application

You can set your web application as default web application. If you set your web application as default, every DNS result that point to your server will go to this web application if there is no matching app name inside your web app. If your visitor access your server by using the IP Address, this web app will be served to the user.

Web Application Alias

For each Web Application, you can create Web Application Alias. The Web Application Alias allows you to create different Web Application but points to the same folder. For example, if you create Web Application “awesomeapp”, the root folder of the Web Application will be, “/home/runcloud/webapps/awesomeapp”. But if you create an alias for this Web Application and name it “otherapp”, the root folder will also be “/home/runcloud/webapps/awesomeapp”.

The Web Application Alias will not have GIT, Script Installer and File Manager menu since it is an alias to another Web Application.

The usage of this Web Application Alias is to allow you to have multiple domain per Web Application with multiple SSL Certificate.

For example, if your Web Application uses Microservice Architecture and depends on Consul, you will have non-existing domain name, example.consul. But now, the Microservice Web Application also have public facing domain name, app1.example.com. If you are using both of these domain name (example.consul and app1.example.com) inside the same Web Application, you will not be able to retrieve SSL Certificate from Let’s Encrypt. By creating the Web Application Alias, app1.example.com will be inside one Web Application and example.consul will be on the alias.

You also can create Web Application Alias to act as a subdomain that points to another folder inside your Web Application. But this setup is highly discourage. Please read more about this inside the Overview section.

Web application summary

This is the summary of your web application. It will show you data related to your web app. Below is the full data of the summary section.

Name Justification
Owner The username of the user who owns the web application.
Total Domain Name Total domains connected to this web application.
PHP Version PHP version of this web application.
Web Application Stack Stack that you use. Either NGINX + Apache2 Hybrid, Native NGINX, Native Nginx + Custom config stack.
Root Path The root folder of your Web Application. PHP can be executed inside this directory only.
Public Path Path to the public folder that your visitors can access.
Total data transfer yesterday Total amount of data that your website served yesterday.
Total data transfer this month Total amount of data that your website served this month.
SSL Provider Let's Encypt or custom SSL provider
GIT Provider The name of GIT repository provider that you are using
Repository GIT repository that you are using
Repository URL URL to your GIT repository from your GIT provider
Branch Current GIT Branch that you are using

Transfer stats

This is the graph that shows you how much data you have served to your visitors. Calculation are in MB. Your server will send the Web Application transfer stats every 12 hours. This section allows you to view transfer data in Daily and Monthly views.

GIT

Overview

One of the best features of RunCloud is that you can use GIT to attach your project to your Web Application. You can do an automatic pull to sync your website with your code. You can also change your GIT branch on the fly. If you are using GIT, you won’t be able to use Script Installer inside the Web Application.

Attaching GIT repository

The first step is to attach the GIT repository to your Web Application and generate a Deployment Key Deployment Key. Please make sure that you are generating the key with the same user as your Web Application owner.

You will need to fill in information about your GIT repository to attach it to your Web Application:

Form Field Justification
Provider The GIT provider which can be a Custom GIT Server, Bitbucket, GitHub GiTLab and also Self Hosted GitLab.
GIT User Only necessary when using a custom GIT server. This indicates the user running the GIT server. Usually the user name is git
GIT Host Domain name of the GIT server. E.g: versioncontrol.example.com. You must have a FQDN as the IP Address isn't supported yet
Repository The repository you want to attach. For example if you use GitHub, your repository URL would be https://github.com/coolcodemy/test. Then you just have to add coolcodemy/test to the repository field.
Branch The repository branch that you want to us, which is usually the master branch.

When you add GIT repository to your Web Application, please wait until it is attached to your Web Application before navigating to another link.

GIT webHook

After you have attached your GIT repository, you will get WebHook URL. You can register this URL to custom GIT Server, Bitbucket, GitHub, GitLab or Self Hosted GitLab repository to enable automatic pull your commit from your origin.

All you have to do is to copy the link, add it to the same repository you have registered to your WebApplication and enable it.

Your Web Application will automatically pull new commit everytime you push your code to your repository.

If you are using GitHub, please make sure that you are using application/json as Webhook Type. We don’t support application/x-www-form-urlencoded.

WebHook history

This is the history of your commit that RunCloud received from WebHook. You can’t do much here except looking at the commit message.

Deployment errors

Starting with agent version 2.0.0 you will be able to view stdout and stderr of your deployment error log. This error log as the name says, will only available for viewing if your deployment is failed.

The stdout and stderr will be pushed to Slack and/or Telegram (if it set inside notification section) and also to your registered email.

The error log will be automatically cleared from the panel after a week.

Changing GIT branch

You can change your GIT branch from here. Please note that if you put the wrong branch, you will see an error inside the server’s log.

You can create two web application and use branch master as the production and development branch for staging server.

Deployment script

When the webhook receives a push request, you might want to run a custom script to clear some cache or upgrade your web application. You can write a script to do this command and you must include your own git merge command.

Deployment script is a bash script but you don't have to include #!/bin/bash at the top of your deployment script.

This script will be terminated after 10 minutes if it does not stop by itself. This is to prevent your server from flooded with script that does not stop by itself.

You must tick Automatically run this script upon new commit push for the script to work.

The script will be running inside your Web Application root folder. If your deployment script includes composer and php command, it will use default PHP-CLI. If you want to run a script using a different PHP version, you must use replacer.

Replacer

Replacer is where you can tell the deployment script to run specific php version. E.g: {php70rc} will run PHP7.0 from /RunCloud/Packages/php70rc/bin/php.

You can always type full path to PHP version if you don’t want to use replacer.

Manual GIT deploy

To manually deploy your script, fill in the command inside your deployment script, click save and then deploy. Your server will follow the command from your script.

Script installer

Script installer allow you to install popular PHP script to your Web Application. Please note that script installer only download the files for you and place it inside your Web Application folder. For the installation, you have to do it yourself. Installing script using script installer wil prevent you from using GIT.

Video tutorial on installing WordPress using Script Installer

Here is the video tutorial on how to install WordPress using RunCloud.

File manager

File Manager allow you to control your file inside your Web Application from RunCloud panel. You can add, edit, delete, change permission and rename files and folders using RunCloud File Manager.

We do not save your files. We are not interested in your files, password, etc. We are also blocking admin from viewing your files. Only you have the access to your files inside your server.

Navigating through file manager is easy. To select multiple files or folder, click the name of the file or folder that your want. To enter the folder, double click the folder name. To create new file or folder, click the button to create file or folder and insert the name of your file or folder. The file or folder that you have created will resides inside your current directory.

Cloud editor

You can edit your files using RunCloud Cloud Editor. You can click one file and click View/Edit to view your file. From there, you can edit your file easily. You can change the syntax of the file editor and change to other theme. File editor theme will be remembered and next time you open up another file to edit, you will always get the same theme. If you are trying to edit a tracked GIT file, the editor will prevent you from saving the file.

Domain name

You can add or delete domain name from here. Please make sure that your domain name already pointed to your server inside your DNS provider. After you have added the domain name, you can open your website using any domain name that you have registered inside RunCloud.

Deleting domain name will also removed it from your Web Application. You won’t be able to access your website using the domain name again until you add it back.

SSL/TLS

Using RunCloud, you can easily deploy your Web Application to use SSL/TLS. The configuration for SSL/TLS will get you the A+ configuration and comply with PCI-DSS, HIPAA and NIST as you can check from here.

You can use free SSL/TLS from Let’s Encrypt or using your own certificate and key.

You can set whether to allow your website visitor to always use HTTPS or also enable HTTP access to them. Or strictly enable HTTPS using HSTS.

Adding SSL/TLS to your web application will have another benefit instead of secure communication between visitor and server. You will get HTTP/2 and Brotli compression out of the box with RunCloud.

Let’s Encypt

Generating Let’s Encrypt certificate is easier using RunCloud. There are two ways to authorize Let’s Encrypt, http-01 and dns-01.

If you are adding new domain name to your Web Application, you need to redeploy the Let’s Encrypt to make it valid.

Let’s Encrypt Certificate have short lived valid time. You must renew your certificate every 3 months. You don’t have to worry about it since we will renew your certificate before the end date.

Now lets talk about each authorization method.

http-01

This method will create authorization file(s) inside your server. Let’s Encrypt will attempt to check whether this/these file(s) exists or not. If it isn’t exists, the authorization challenge will fail.

This authorization method will check the existence of the files(s) based on A, AAAA or CNAME DNS record. If the DNS record does not pointing to your server, the challenge will fail.

http-01 authorization method does not support wildcard ssl.

dns-01

This method will create a DNS TXT record(s) inside your DNS service provider. With this authorization method, Let’s Encrypt will try to check the existence of the TXT record(s). If the record(s) exists, the challenge will be valid.

To use this authorization method, you need to supply 3rd Party API to use. Currently we only support Cloudflare, Linode and Digital Ocean DNS.

dns-01 authorization method does support wildcard ssl.

Video tutorial on requesting Let’s Encrypt SSL/TLS certificate

Here is the video tutorial (old tutorial) on how to request Let’s Encrypt certificate using RunCloud.

Custom SSL/TLS provider

Using custom SSL/TLS provider is straight forward. You just have to buy certificate either from Comodo, Verisign or any SSL provider. After that, add your certificate and key to RunCloud. We will automatically configure them for you.

When you need to change you certificate, just replace the old certificate value with the new one and click save.

Web application settings

This section contains two section which is PHP Version selection and Web Server Setting.

PHP version

Here you can change your Web Application PHP version with just one click. Changing PHP version also available for free user.

Web server configuration

The web server configuration consists of several section:

Public path

This is where you can change your web application public path. For example if you are using PHP framework, you can change your public path to /path/to/framework/public

Web application stack

There are two stack that you can choose from here.

1. NGINX + Apache2 Hybrid Stack:
NGINX works as reverse proxy for Apache2. Different from most setup, this stack doesn’t fully proxying Apache2. NGINX is really best at serving static content. By using this stack, your static files (eg: css,js,images,fonts) will be served by NGINX. If it is PHP, NGINX will pass it to Apache2 and the request will be pass to PHP-FPM. This setup is great if you are leveraging on .htaccess.

2. Native NGINX Stack:
Your sites will be fully controlled by NGINX. If it is PHP files, NGINX will pass it to FastCGI to communicate with PHP-FPM. This stack doesn’t support .htaccess. If you are going to do rewrite or including your own config, you can extend NGINX config by following this example.

3. Native NGINX + Custom config Stack:
Your sites will be fully controlled by NGINX. This stack will not serve your PHP file. You have to manually extend the config by following this example. This is suitable if you want to run nodejs/python/golang/websocket/ror/etc.

Web application stack mode

There are two stack mode that you can choose from here.

1. Production
This will instruct visitor to your web application to cache static files (js/css/fonts/images/html) inside their browser.

2. Development
This will prevent the browser from caching your static files (js/css/fonts/images/html). Development mode does not prevent from other caching method such as Redis, Memcached or in-app caching.

NGiNX

This is the configuration for your NGiNX block for the Web Application. Changing this value will have no effect on other Web Application that you own

Checkbox Reference Link
Clickjacking Protection https://en.wikipedia.org/wiki/Clickjacking
XSS Protection https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection
MIME Sniffing Protection https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options

FPM

This is the configuration for PHP-FPM settings for this Web Application. It will have no effect on other Web Application.

Form Field Justification
Process Manager How the PHP-FPM run. There are three pm settings that you can choose which is ondemand, dynamic and static. Our default settings use ondemand because it will scale depending on number of visitors you have on your website. Read here for more info
pm.start_servers You can only set this if pm is set to dynamic. When you start the FPM process, it will start with this number of process
pm.min_spare_servers The desired minimum number of idle FPM processes. Used only when pm is set to dynamic
pm.max_spare_servers The desired maximum number of idle FPM processes. Used only when pm is set to dynamic
pm.max_children Allowed number of process for PHP-FPM to fork
pm.max_request The number of request can each PHP-FPM child serves

PHP

This is the PHP configuration for your Web Application. It will have no effect on other Web Application. It will also have no effect on PHP-CLI.

Form Field Justification
open_basedir The maximum parent folder that the web application can execute. PHP won't be executing outside of this folder. If you have to change this setting, there is something unusual going on inside your web application. It is safe to say that you code your web application wrongly
data.timezone The timezone that will be used inside your web application. If you have set your timezone inside the profile, this value will follow your current timezone.
disable_function PHP function that should be disable for security reason. If you need to use one or more of this php function, do not blindly remove all function. You might pose high security vulnerability if you remove everything from here.
max_execution_time The maximum number of seconds that PHP script can execute. PHP script will stop itself after reaching this time
max_input_time The maximum number of seconds that a script allows to receive input from website visitor such as uploading picture. If your website host video uploading site, you might need to increase this value
max_input_vars The maximum number of variables can a request handle.
memory_limit The maximimum amount of memory (in MB) that a script allowed to use
post_max_size The maximum size of post request (in MB) your server can handle.
upload_max_filesize The maximum size of uploaded file your Web Application can handle. Usually same or lower than post_max_size.
sesion.gc_maxlifetime The maximum number of seconds your PHP session can be valid before garbage collector delete your session.
allow_url_fopen Allow your php script to open remote files from another server. The default value is on, but if you don't use it, you may disable this setting.

Web Server Log

This is where you can see the Web Server error and access log. Depending on your Web Application stack, if you are using Apache2 + Nginx Hybrid stack, you can access Nginx Access Log, Nginx Error Log, Apache2 Access Log and Apache2 Error Log. While using Native Nginx or Native Nginx + Custom config stack, you can only see Nginx Access Log and Nginx Error Log.

Log

This is your Web Application log. Most of Web Application log will be registered in here.