Documentation

Technical information about CrossBox can be found here. Feel free to browse around to learn more about installing and running CrossBox on your server(s).

CrossBox Server

CrossBox Server

Requirements

Standalone Version

  • 1 CPU or vCPU
  • 512 MB of RAM
  • 5GB of Disk Space

Following features require additional memory when enabled:

  • Anti-Spam - 250 MB of RAM
  • Anti-Virus - 600 MB of RAM
  • TURN/STUN - 50 MB of RAM
  • CrossBox Document Converter (CDC) - 100 MB of RAM

To run a standalone version with all features enabled, we recommend you install CrossBox on a server with at least 2GB of RAM.

Don't forget to plan out the disk space which will be used to store emails, attachments, files and other storable objects by the users.

Supported Operating Systems

CrossBox Server runs on any x86-64 (64 bit) Linux based operating system, including but not limited to:

  • RedHat/CentOS/CloudLinux 6+
  • Ubuntu 12.04+ 
  • Debian 7+ 
  • Fedora 13+ 
  • OpenSUSE 11.3+ 
  • ArchLinux
  • Slackware

Control Panel Version

It's common for servers that utilize a control panel to have most of the needed services already running and in place.

Thus, when installing on a server that has cPanel, Plesk, DirectAdmin, VestaCP, Webmin, CWP or any other control panel already running, CrosBox will auto-detect and use the following services automatically:

  • MySQL
  • Exim
  • Dovecot
  • MailScanner
  • ClamAV
  • CSF
  • Firewalld
  • UFW
  • Solr

This effectively reduces the total memory needed for CrossBox to run to just 512 MB of RAM, when used alongside the control panel.

Supported Control Panels

cPanel, Plesk, and Direct Admin currently have deep-integrations available. 

However, you can still use CrossBox with any control panel due to its plug and play nature but unlike with the supported control panels, some functions are not automated and may require manual action.

Software Dependencies

You don't need to install any new software dependencies for CrossBox to work. 
It runs on almost any Linux powered server (known as portable software) and won't install anything via your system's package manager (like yum, apt-get, pacman, etc). Therefore, it will never interfere with other software/packages/libraries you may already have running on the server.

Other Dependencies

Hostname

Make sure that before installing CrossBox your server has a resolvable hostname.

PTR (Reverse DNS)

We recommend that the server has a valid PTR (Reverse DNS) record that matches the server's hostname.
A valid PTR record is important for good e-mail delivery.
Most VPS/Dedicated server providers allow you to edit a PTR record via the control panel they provide. 

Root user

 A root user account and SSH access are required to install a CrossBox Server.

Home Directory

Your system needs to have a /home directory. If it doesn't exist, CrossBox Installer will automatically create it.

Let's start

Are you ready to get started?
Continue to Quick Installation Guide and have CrossBox up and running in under 5 minutes.

CrossBox Server

Quick Installation

Intro

First, please make sure that you checked out the Requirements before you start with the installation.

Sign Up

To install CrossBox you need to have a valid CrossBox.io account and an active license.

Single Server Setup

Here we will show you how to install CrossBox on a single server.

Multiple Server Setup

If you plan to install CrossBox on multiple servers, please head out to our CrossBox Cluster documentation to learn how to create a master-slave cluster.


Installing in 5 Easy Steps


 STEP ONE 

SSH into your server and run the following command as root:

sh <(curl https://cdn.crossbox.io/install.sh || wget -O - https://cdn.crossbox.io/install.sh)

Then proceed to log in with your CrossBox.io account:

pehQubv.png

After a successful login, you'll find the URL that you can now use to start the installation via your web browser:

0gi6h52.png


 STEP TWO 

Open your favorite web browser and paste the URL you copied


 STEP THREE 

Click your way through

Almost everything is already pre-populated for you and the entire process takes about ten minutes or often less, depending on your server's performance.

116.203.63.82_5000_-(2).png

Detailed Help

If you're not sure what to enter in a certain field during the installation, just click on the "Learn more" link which is displayed beneath it:

116.203.63.82_5000_-(3).png

By clicking it, you'll be taken directly to that option's more detailed documentation.


 STEP FOUR 

Start the installation

After you click the "Install" button, CrossBox will start setting everything up. You can track the progress in real-time as shown below:

116.203.63.82_5000_-(4).png

 STEP FIVE 

Finish the installation

After the installation finishes successfully, you'll see a link which leads you to your CrossBox App.

116.203.63.82_5000_-(5).png

You can now log in as admin to manage your installation.

To create users, depending on the type of installation, you should get familiar with:

CrossBox Server

Options in Details

Server

Tweaking CrossBox Server to fit your needs is as easy as enabling and disabling features with a simple checkbox click. CrossBox will auto-detect if some kind of a control panel is already installed on the server and will auto-adjust itself. Here we have listed all the options and associated help descriptions.   

Hostname

CrossBox will try to automatically resolve a hostname of the server it's being installed onto.

However, make sure that before installing CrossBox you have a valid PTR (Reverse DNS) record that matches your hostname and that your hostname can be successfully resolved.

Public IP Address

CrossBox will try to automatically resolve an IP address of the server it's being installed onto.

App Port

Enter a Port number that CrossBox will bind to and listen on.

If you're installing master server this option is disabled and ports 80/443 are enforced. Otherwise, you can specify a custom port.

Please make sure that App port(s) are not used by some other software running on the server.

If you have a firewall in place, please make sure that binding to these ports is allowed.

App Port cannot be changed after the installation.

SSL

We strongly recommend that you enable the SSL feature. Not only it will help protect data being sent over the network from prying eyes, but it is also needed for audio and video calls to work. It is very easy to set up and you have four options to choose from:

  • Generate SSL certificates automatically (by using Let's Encrypt Certbot)
  • Select from an auto-detected list (will scan the system for existing certificates) - this is visible if the installer detects SSL certificates
  • Enter .crt/pem .key paths (lets you enter paths to certificate files)
  • Upload .crt/pem and .key files (lets you upload certificate files)
TURN/STUN Server

CrossBox uses Coturn as a fast and reliable TURN/STUN server. It is responsible for streaming audio and video data during the CrossBox audio/video conference and for relaying media traffic when persons attending the call can't reach each other directly via the peer-to-peer protocol. This is most often the case when the person is behind a corporate firewall.

Overall, enabling a TURN/STUN server will greatly improve the quality of audio and video calls. The CrossBox Installer will give you the ability to choose if you wish to enable TURN/STUN integration and will also allow you to decide where it should be hosted.

You can choose to install it on the same server as CrossBox or you can enter an external server to offload audio and video streaming to a separate machine in the case you have thousands of concurrent calls being made.

If you plan on having more than 50 people streaming audio and video at the same time, please make sure that you allocate enough CPU/Network resources for your TURN/STUN server. The other approach would be to offload media streaming to a Coturn server hosted on another machine, by choosing "Use external coturn server" and filling in Host and SSL Host fields.

Coturn Non-SSL Port

Enter a non-SSL port that Coturn will use. The default Coturn non-SSL port is 3478.

Coturn UDP Port Range

You may leave the default value. If not, please enter a port range in format 12345:13456. The default value is 49152:65535.

Updates

CrossBox has a built-in update system that keeps your installation up to date and automatically updates CrossBox when new updates are available.

At what hour to perform an update

Enter an hour when you wish to check for updates. Uses a 24h format and accepts a number between 0 and 23. 0 means 00:00.

Application Limits

Max Number of Workers

Max number of CPU cores that the application will utilize. Depending on the application traffic/usage you can specify a maximum number of workers based on the number of cores your server has.

Each worker takes about 70-100 MB of RAM.

Max Request Size

In megabytes, enter maximum request body size that the end user can send. For example, users won't be able to upload a file larger than what's defined here. The default value is 1024MB.

Chat Channel Max Participant Count

The maximum number of participants allowed in a chat channel. Increase this if you plan on having more than 50 persons attending. This is a per one channel (room) limitation.

CrossBox Admin

Admin E-mail Address

Admin e-mail address. You may use any email address you want.

Admin Password

This password should be very complex.

Localization

Default Language

Choose the default language for the App. If you want to add your own language, you can do so by translating a language file and sending it back to us. We will then ship it with the next update.

Logging

Error Reporting

In case of an error, the server will securely send us the traceback and the message - so our team can detect and fix the issue ASAP, with an aim of minimizing the bug's impact on larger audiences.

MySQL

Use CrossBox MySQL database

Enable if you don't have a MySQL server already running on the server.

If you enable this feature, CrossBox will use its own MariaDB (MySQL) server for storing users' data. Otherwise, it will try to connect to a MySQL server already running on the system and use that server for storing database data.

You can also uncheck this option to enter MySQL server details manually. This is useful if you're connecting CrossBox to remote MySQL server or a MySQL Cluster.

Root MySQL user is required. The root privileges are required because CrossBox manages the creation of users' databases. 

Mail

Enable mail server integration
CrossBox has two ways of integrating with a mail server:
  1. Use the mail server already running on the machine (for example when installing on a cPanel/Plesk/Direct Admin server)
  2. Automatically install and set up a CrossBox mail server (when installing a bare metal/standalone version, or a mail server is not found on the server)

In the first case, the installer will try to find locally available IMAP/SMTP servers and use those for everything related to email.

In the second case, you'll be able to enable or disable following mail server features:

Enable Anti-Virus Service

Enable this if you want an anti-virus to scan emails for malicious content. Currently, only ClamAV is supported. If you have ClamAV already running on the server, CrossBox will use that one automatically.

ClamAV requires 600 MB of RAM.

Enable Anti-Spam Service

Enable this if you want an anti-spam service to check whether the e-mail being sent/received is spam or not. Automatic spam/ham learning is also enabled with this service.

Enabling this service requires an additional 250 MB of RAM.

E-mail Message Max Size

Enter the maximum allowed email message size in megabytes. Generally, it should not exceed 50MB.

Automatically create postmaster@ and admin@

This can save you some time by creating often needed email addresses automatically for you.

Other

Google Analytics

To track App usage in real time you need to enter a valid Google Analytics Tracking ID in UA-XXXXX-Y format.

CrossBox Document Converter (CDC)

Service that allows users to view (.docx, .doc, .xls, .ppt + many others) without having to download the files on their device. Users can also download PDF versions of various formats that are supported. This service requires at least 100MB of RAM

Branding

Branding is a great way to white label CrossBox as your own product or service. You can give it a custom name, upload your own logo and change the color scheme to best match your brand. Also, branding addon allows you to have a fully branded CrossBox Client Apps (Web, Desktop, Android & iOS).

Branding feature is most useful for service and hosting providers.

App Name

Enter a custom name for the application.

App Description

Enter a custom Application slogan or a motto. This is usually shown beneath the App Name.

App Product URL

URL of the web page advertising the application. Users are taken to this URL when they want to find out more about the App.

Theme

Lets you brand the App with your own color scheme. Apart from that, you can also upload your own App logo. Image for the logo should be in a PNG format with 1024x1024 px dimensions. CrossBox will then use that image to create logo versions of different dimensions used throughout the application.

iOS and Android App Settings

iOS and Android sections let you define App manifests that Apple and Google stores require when publishing the Apps. You will need to fill in a couple of details:

  • App Identifier (This is the Application ID. For example, com.example.appname)
  • App Author (The name of the Author)
  • App Author E-mail (E-mail address of the author)
  • App Support URL (URL where you provide customer support)
  • App Store URL (URL for downloading iOS app)
  • Play Store URL (URL for downloading Android app)
Push Notifications

This enables push notifications for your branded CrossBox Android and iOS Apps. They keep your end users up to date with new emails, chats, calls, files, and reminders. 

GCM is not recommended anymore. Please use FCM - Firebase Cloud Messaging. We strongly recommend that you use FCM for both Android and iOS versions.

When using FCM, you need to obtain FCM Sender ID and FCM Key. Please follow this blog post to find out how to obtain these.

If, however, you must use GCM, then you'll need to fill in GCM Sender ID and GCM Key. To obtain these, please start here.

We do not recommend using APNs, use FCM instead. If you insist on using APNs, then you'll need to obtain APNs certificate as explained in "Generate an APNs client TLS certificate" and then upload it by using "Upload APNs Certificate" upload box during the installation.

CrossBox Server

Admin Area

Intro

CrossBox features a simple to use administration interface which is used for managing a CrossBox server.

Accessing Admin Area

To access the administration, visit your CrossBox URL and log in by using your admin credentials.

Restoring access to Admin Area

If you lost or forgot your admin credentials, these are the CLI commands that you can run via SSH (as root) to restore them:

$: crossbox info - get general information about the CrossBox installation

$: crossbox change-admin-password - change admin password

$: crossbox change-admin-email - change admin email address

Adding a Domain (Standalone only)

  • Go to Admin -> Servers
  • Pick a server where you want the domain to reside
  • Go to Domains -> Click on the FAB button in the bottom-right corner
  • Fill in the form: