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
- Quick Installation
- Options in Details
- Admin Area
- Command Line Tools
- Performance Tuning
- Control Panels
- Third Party Apps
- Building Android and iOS apps
- App Connector
Even though CrossBox is highly portable, make sure that your server satisfies the listed server requirements.
Supported Operating Systems
CrossBox Server runs on any x86-64 (64 bit) Linux based operating system that has glibc version 2.17 and up.
Listed below are minimum required distribution versions. Versions equal to or greater than the ones listed below are fully supported:
- RedHat/CentOS/CloudLinux 7
- Ubuntu - 16.04 LTS xenial
- Debian - 9 stretch
- Fedora - 30
- OpenSUSE - 15.1
- Arch Linux
- Slackware - 14.2
- Mint - 18.3 sylvia
You can check you glibc version by running
via the command line interface.
CrossBox Server can run on a small virtual machine, a big dedicated server, or anything in between.
CPU and memory requirements vary depending on the version you'll be running, the number of enabled features, and the number of concurrent users.
The standalone version comes with everything prepackaged and preconfigured. It is intended for installing and running on a fresh, clean server.
Bare-minimum (use only core features):
- 1 CPU
- 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
- Document Converter (CDC) - 100 MB of RAM
- TrustedLink (email assets SSL proxy) - 50 MB of RAM
To run a standalone version with all features enabled, we recommend you install CrossBox on a server with at least 1 CPU and 2GB of RAM.
Control Panel Version
It's common for servers that utilize a control panel to have many of the needed services like MTA, mail server, anti-spam service, and anti-virus already running and in place.
Therefore, when installing on a server that's running cPanel, DirectAdmin, or Plesk, we auto-detect and use the following services automatically:
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
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.
If you want to calculate your CPU and RAM resources in advance, here are the numbers:
1CPU, 2GB RAM for 100 concurrent users.
For example, if your plan is to host 100 concurrent users, you'll need:
- 1 CPU
- 2GB RAM
If your plan is to host 200 concurrent users:
- 2+ CPU
- 4GB+ RAM
You don't need to install any new software dependencies for CrossBox to work. It comes pre-compiled and runs isolated from the rest of the system.
It won't install anything via your system's package manager (like yum, apt-get, pacman, etc), and therefore, will never interfere with other software/packages/libraries you may already have running on the server.
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.
A root user account and SSH access are required to install a CrossBox Server.
Web Terminal with root user access can also be used (for example WHM Terminal).
Your system needs to have a /home directory. If it doesn't exist, CrossBox Installer will automatically create it.
Are you ready to get started?
Continue to Quick Installation Guide and have CrossBox up and running in a couple of minutes.
First, please make sure that you checked out the Requirements before you start with the installation.
To install CrossBox you need to have a valid and active license. If you don't have one, you can purchase it here.
Here we will show you how to install CrossBox on a single server. If you plan to install CrossBox on multiple servers, please head out to our CrossBox Cluster documentation to learn how you can unify communication across different servers and configurations.
Run the Command
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:
After a successful login, you'll find the URL that you can now use to start the installation via your web browser.
The URL will be similar to the one shown below, but unique to your installation instance:
Access the Installation via the Web Browser
Open your favorite web browser and paste the URL that you copied.
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.
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:
By clicking it, you'll be taken directly to that option's more detailed documentation.
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:
Finish the Installation
Options in Details
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.
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.
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.
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)
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.
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.
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.
Admin E-mail Address
Admin e-mail address. You may use any email address you want.
This password should be very complex.
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.
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.
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.
Enable mail server integration
- Use the mail server already running on the machine (for example when installing on a cPanel/Plesk/Direct Admin server)
- 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.
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 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.
Enter a custom name for the application.
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.
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)
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.
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 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: