- 26 Mar 2021
- 11 Minutes to read
-
Print
-
DarkLight
-
PDF
Deploy Server On-Premise
- Updated on 26 Mar 2021
- 11 Minutes to read
-
Print
-
DarkLight
-
PDF
Overview
This article will outline the recommended architecture and deployment details for running the SecureCircle server.
Current Version
The SecureCircle server versions can be downloaded from the Server Downloads page.
System Requirements
The minimum system requirements for the SecureCircle server, assuming all components are running, are as follows:
- CPU: 2 core, 2.5GHz
- Memory: 4GB
- Disk space: 8GB
- Docker CE v17.03.0-ce (or above)
- Docker Compose v1.17.0 (or above)
The minimum system requirements support a peak load of 3000 requests per second, or around 20000 users. System requirements may need to be increased depending on the number of concurrent users. Doubling the server's CPU and networking resources will yield around a 1.5x performance increase.
Quick-start
This section assumes the SecureCircle server will be placed on a Linux-based host.
- Download the appropriate docker-compose.yml file, .env file, and container bundles from the Server Downloads page.
- Install Docker CE (community edition)
- https://docs.docker.com/install/
- Docker defaults to storing its data in /var/lib/docker. If you wish to change this:
$ cat > /etc/docker/daemon.json << EOF
{ "graph": "/new/path/docker" }
EOF
- Install Docker Compose
- https://docs.docker.com/compose/install/
- Remaining steps will need to be completed with either the root account, or an account that is a member of the docker group.
- Obtain a root shell.
$ sudo -i
- OR Add your user to the docker group.
$ sudo usermod -a -G docker $(whoami)
You will need to logout and log back in, or run:
$ newgrp docker
- Create a new directory to hold the Docker Compose configuration.
$ mkdir ~/server
$ cd ~/server
- Place the downloaded docker-compose.yml file (from step 1) into the directory.
- Review the .env file. Items that will need configuration are marked with CHANGEME.
- The base_domain and NGINX_SERVER_NAME variables will need to be set to the hostname used for accessing the SecureCircle server.
- For example, if it is https://securecircle.local/ enter securecircle.local.
- Load the downloaded container bundles (from step 1) into the local Docker image cache.
$ docker load --input file.tar.gz
- Ensure ports that will be used by the securecircle-http container are available on the system. By default it will listen to port 80 for HTTP and 443 for HTTPS.
- The server's certficate chain in PEM format must be placed in a file called chain.
- The private key PEM format for the server's certificate must be placed in a file called key. This key cannot be password protected.
- Place agent bundles into the appropriate subfolders within a folder called download.
- For mac, add an additional subfolder called resources Place bundle.dat here
- Your directory should contain files in the following locations:
$ tree
.
├── chain
├── docker-compose.yml
├── download
│ ├── android
│ │ └── fhfs.apk
│ ├── linux
│ │ └── fhfs.run
│ ├── mac
│ │ ├── fhfs.pkg
│ │ └──resources
│ │ └──bundle.dat
│ └── win
│ └── fhfs.exe
└── key
- Start the containers
$ cd ~/server && docker-compose up -d
Monitor the container startup by tailing the logs:
$ docker-compose logs -f
If the containers must be stopped:
$ docker-compose down
Upgrading the Server
- Download the new container versions from the Server Downloads page. They can be downloaded directly on the Docker host, or transferred there.
- Load the downloaded images into the Docker image cache with docker load --input file.tar.gz.
- Bring the server down with docker-compose down.
- Replace the existing docker-compose.yml with the updated version from the Server Downloads page.
- Bring the server up with docker-compose up -d.
## Architecture
The SecureCircle server is packaged as a set of Docker containers deployed via Docker Compose.
-
securecircle-server
The SecureCircle server Java web application set running in Apache Tomcat -
securecircle-ui
Assets for the server's administrative web interface. -
securecircle-sharing-portal
Assets for the server's sharing portal. -
securecircle-db
A default MySQL container provide for testing. -
securecircle-http
An nginx based HTTP(S) front-end for the securecircle-server container. -
securecircle-converter
Utilizes LibreOffice to convert documents to PDFs for use by SecureSend's View option. -
redis
An optional local cache. Recommended for use with external database
Uploading agents to the server for download by endpoints
Agents must be requested from SecureCircle. Please file a ticket if new agents are needed.
The following information must be provided, it is built into each individual client installation:
- The fully qualified domain name of the SecureCircle server.
- The SSL certificate and authority chain (root and/or intermediate authorities) the server is using.
Serving client installation packages is done by the securecircle-http container. By default the download folder on the host system (relative to the docker-compose.yml file) is mapped to /var/htdocs/download in the securecircle-ui container.
An example directory structure for the various client bundles is as follows:
$ tree download
download
├── android
│ ├── fhfs-0.0.1.apk
│ └── fhfs.apk -> fhfs-0.0.1.apk
├── linux
│ ├── fhfs-0.0.1.run
│ └── fhfs.run -> fhfs-0.0.1.run
├── mac
│ ├── fhfs.pkg -> fhfs-0.0.1.pkg
│ ├── fhfs-0.0.1.pkg
│ └── resources
│ └── bundle.dat
└── win
├── fhfs.exe -> fhfs-0.0.1.exe
└── fhfs-0.0.1.exe
High Availability
The SecureCircle server can be made highly available with the following considerations:
- An external MySQL database setup in a high availability mode must be provided.
- Multiple securecircle-server, securecircle-http, securecircle-ui, and securecircle-sharing-portal containers may be run.
- An external load balancing setup pointing to the securecircle-http containers must be provided.
SecureCircle server application (securecircle-server)
This container packages the core Java WAR (web application archive) files responsible for main functionality of the SecureCircle server. They are run via the Apache Tomcat server.
Environment
The following environment variables are available for configuration. These can also be used as Java properties where noted.
Variable | Default Value | Description | Used in webapps... | Env | Prop |
---|---|---|---|---|---|
base_domain | localhost | The hostname that will be used for accessing the server. | API, Router, Tracker, Shrecker | ✓ | ✓ |
base_domain_alias | Local Server | The server name that will be presented to the agent | Tracker | ✓ | ✓ |
logging_db_type | mysql | The type of database to use. Options are mysql or mssql | API, Router, Shrecker, Tracker | ✓ | ✓ |
folium_runtime_db_type | See above | See above | API, Router | ✓ | ✓ |
folium_spare_db_type | See above | See above | Tracker | ✓ | ✓ |
folium_system_db_type | See above | See above | API, Tracker, Shrecker | ✓ | ✓ |
folium_tracker_db_type | See above | See above | API, Tracker, Shrecker | ✓ | ✓ |
share_db_type | See above | See above | API, Tracker, Shrecker | ✓ | ✓ |
logging_db_url | jdbc:mysql://folium-db:3306/Logging | JDBC URI to connect to MySQL (compatible) server | API, Router, Shrecker, Tracker | ✓ | ✓ |
folium_runtime_db_url | jdbc:mysql://folium-db:3306/Runtime | See above | API, Router | ✓ | ✓ |
folium_spare_db_url | jdbc:mysql://folium-db:3306/Spare | See above | Tracker | ✓ | ✓ |
folium_system_db_url | jdbc:mysql://folium-db:3306/System | See above | API, Router, Tracker, Shrecker | ✓ | ✓ |
folium_tracker_db_url | jdbc:mysql://folium-db:3306/Tracker | See above | API, Tracker, Shrecker | ✓ | ✓ |
share_db_url | jdbc:mysql://folium-db:3306/Share | See above | API, Tracker, Shrecker | ✓ | ✓ |
logging_db_username | root | Username to use when connecting to the MySQL server. | API, Router, Shrecker, Tracker | ✓ | ✓ |
folium_runtime_db_username | root | See above | API, Router | ✓ | ✓ |
folium_spare_db_username | root | See above | Tracker | ✓ | ✓ |
folium_system_db_username | root | See above | API, Router, Tracker, Shrecker | ✓ | ✓ |
folium_tracker_db_username | root | See above | API, Tracker, Shrecker | ✓ | ✓ |
share_db_url | root | See above | API, Tracker, Shrecker | ✓ | ✓ |
logging_db_password | password | Password to use when connecting to the MySQL server | API, Router, Shrecker, Tracker | ✓ | ✓ |
folium_runtime_db_password | password | See above | API, Router | ✓ | ✓ |
folium_spare_db_password | password | See above | Tracker | ✓ | ✓ |
folium_system_db_password | password | See above | API, Router, Tracker, Shrecker | ✓ | ✓ |
folium_tracker_db_password | password | See above | API, Tracker, Shrecker | ✓ | ✓ |
share_db_password | password | See above | API, Tracker, Shrecker | ✓ | ✓ |
logging_db_pool_max_pool_size | 10 | Maximum connections allowed in the database connection pool | API, Router, Shrecker, Tracker | ✓ | ✓ |
folium_runtime_db_pool_max_pool_size | 50 | See above | API, Router | ✓ | ✓ |
folium_spare_db_pool_max_pool_size | 50 | See above | Tracker | ✓ | ✓ |
folium_system_db_pool_max_pool_size | 50 | See above | API, Router, Tracker, Shrecker | ✓ | ✓ |
folium_tracker_db_pool_max_pool_size | 50 | See above | API, Tracker, Shrecker | ✓ | ✓ |
share_db_pool_max_pool_size | 50 | See above | API, Tracker, Shrecker | ✓ | ✓ |
logging_db_pool_min_idle | 1 | Minimum amount of time an idle connection in the pool will stay connected (in seconds) | API, Router, Shrecker, Tracker | ✓ | ✓ |
folium_runtime_db_pool_min_idle | 1 | See above | API, Router | ✓ | ✓ |
folium_spare_db_pool_min_idle | 1 | See above | Tracker | ✓ | ✓ |
folium_system_db_pool_min_idle | 1 | See above | API, Router, Tracker, Shrecker | ✓ | ✓ |
folium_tracker_db_pool_min_idle | 1 | See above | API, Tracker, Shrecker | ✓ | ✓ |
share_db_pool_min_idle | 1 | See above | API, Tracker, Shrecker | ✓ | ✓ |
show_smtp_debug_info | false | Show debug information for outgoing emails | API, Router, Tracker, Shrecker | ✓ | ✓ |
smtp_socket_timeout | 20 | Set the socket timeout for SMTP connections | API, Router, Tracker, Shrecker | ✓ | ✓ |
smtp_connection_timeout | 10 | Set the connection timeout for SMTP connections | API, Router, Tracker, Shrecker | ✓ | ✓ |
mail_templates_path | /var/velocity/mail | Location of Velocity templates used for outgoing emails | API, Router, Tracker, Shrecker | ✓ | ✓ |
mail_images_url | https://${base_domain}/images | URL for images linked into outgoing emails | API, Router, Tracker, Shrecker | ✓ | ✓ |
sc_redis_host | sc-redis | Hostname of optional Redis database cache | API, Router, Tracker, Shrecker | ✓ | ✓ |
sc_redis_port | 6379 | Port of Redis cache | API, Router, Tracker, Shrecker | ✓ | ✓ |
sc_redis_timeout_millis | 1000 | Connection timeout for Redis cache | API, Router, Tracker, Shrecker | ✓ | ✓ |
sc_redis_clear_before_use | false | Clear Redis cache on connection | API, Router, Tracker, Shrecker | ✓ | ✓ |
key_cache_lifetime_seconds | 3 | TTL for internal key cache (in seconds) | Tracker, Shrecker | ✓ | ✓ |
sc_remote_state_cache_ttl | 1 | TTL for remote state cache (in seconds) | API, Router, Tracker, Shrecker | ✓ | ✓ |
sc_local_state_cache_ttl | 0 | TTL for local state cache (in seconds) | API, Router, Tracker, Shrecker | ✓ | ✓ |
confirmation_url | https://${base_domain}/activations/ | URL used for device confirmation | API, Tracker | ✓ | ✓ |
download_url | https://${base_domain}/web/download.html | URL used for agent downloads | API | ✓ | ✓ |
success_url | https://${base_domain}/web/success.html | URL used for successful actions | API | c✓ | ✓ |
error_url | https://${base_domain}/web/error.html | URL used for server errors | API | ✓ | ✓ |
reset_password_url | https://${base_domain}/web/resetPassword.html | URL used for password reset requests | API, Router | ✓ | ✓ |
reset_password_code_size | 26 | Size of password generated during reset | API, Router | ✓ | ✓ |
reset_password_code_allowed_lifetime_seconds | 1800 | TTL for password reset requests | API, Router | ✓ | ✓ |
url_index | https://${base_domain}/index.html | Redirect page for the server's index page | Router | ✓ | ✓ |
url_login | https://${base_domain}/login.html | Redirect page for the server's login page | Router | ✓ | ✓ |
maxmind_geoip_database_path | /opt/folium/geoip/maxmind/GeoLite2-City.mmdb | Path to MaxMind GeoIP database | Tracker | ✓ | ✓ |
sharing_confirmation_lifetime_seconds | 1800 | Confirmation emails will expire after this time. | Shrecker | ✓ | ✓ |
converter_url | https://sandbox.securecircle.com:4443 | Shrecker | ✓ | ✓ | |
LOG_FILE_APPENDER_PATH | /var/log/securecircle | The path that server logs will be written to | API, Router, Tracker, Shrecker | ✓ | ✗ |
LOG_FILE_APPENDER_LEVEL | INFO | The level of logging output to files | API, Router, Tracker, Shrecker | ✓ | ✗ |
CONSOLE_APPENDER_LEVEL | OFF | The level of logging output to console (stdout) | API, Router, Tracker, Shrecker | ✓ | ✗ |
wopi_enabled | true | Enable WOPI integration in Sharing Portal | Shrecker | ✓ | ✓ |
wopi_url | https://wopi.securecircle.com | The URL of the WOPI server | Shrecker | ✓ | ✓ |
User interface (securecircle-ui)
This container is used to provide a Docker volume containing the server's user interface assets.
Sharing portal (securecircle-sharing-portal)
This container is used to provide a Docker volume containing the server's sharing portal assets.
MySQL (compatible) database (securecircle-db)
This container provides a MySQL database for the SecureCircle server application to utilize.
If an existing MySQL database is available this can be configured via the db environment variables in the Tomcat container.
Backing up the database
When running with the reference Docker Compose configuration, the MySQL database can be backed up and restored with the following commands:
# Backup the database
$ docker-compose exec securecircle-db sh -c "MYSQL_PWD=CHANGEME mysqldump -uroot --all-databases > /var/lib/mysql/backup.dump"
# Find the name of the database container. In this example it is server_securecircle-db_1
$ docker-compose ps | grep securecircle-db
server_securecircle-db_1 docker-entrypoint.sh --cha ... Up 3306/tcp, 33060/tcp
# Copy the backup from the container to the Docker host
$ docker cp server_securecircle-db_1:/var/lib/mysql/backup.dump .
# Find the name of the database container. In this example it is server_securecircle-db_1
$ docker-compose ps | grep securecircle-db
server_securecircle-db_1 docker-entrypoint.sh --cha ... Up 3306/tcp, 33060/tcp
# Copy the backup from the Docker host to the container
$ docker cp backup.dump server_securecircle-db_1:/var/lib/mysql/backup.dump
# Restore the database
$ docker-compose exec securecircle-db sh -c "MYSQL_PWD=CHANGEME mysql -uroot < /var/lib/mysql/backup.dump"
Environment
Variable | Default Value | Description |
---|---|---|
MYSQL_ROOT_PASSWORD | Nonel | This variable is mandatory and specifies the password that will be set for the MySQL root superuser account. |
Manual provisioning
The SecureCircle server requires the following databases to be available. If you are connecting to an external database server and not utilizing the provided container they will need to be created.
Be sure to update the appropriate db environment variables in the securecircle-server service. Additionally, the db reference in the entrypoint: /opt/wait-for-it.sh -s -t 120 db:3306 -- line, must be replaced.
CREATE DATABASE IF NOT EXISTS Logging;
CREATE DATABASE IF NOT EXISTS Tracker;
CREATE DATABASE IF NOT EXISTS Runtime;
CREATE DATABASE IF NOT EXISTS Share;
CREATE DATABASE IF NOT EXISTS System;
CREATE DATABASE IF NOT EXISTS Spare;
nginx HTTP(S) front-end (securecircle-http)
This container provides a basic front-end load balancer for the SecureCircle server application.
TLS
A certificate chain in PEM format needs to be provided to the securecircle-http container in chain, and a private key in key (relative to docker-compose.yml). These files will be used to provide HTTPS service.
These files are not required if the NO_USE_SSL environment variable is set.
If your certificate authority is not well-trusted (such as an internal CA, or a self-signed certificate) the endpoint software will need to be built with your certificate chain. It will not connect otherwise.
Environment
Variable | Default Value | Decription |
---|---|---|
NGINX_SERVER_NAME | local.securecircle.io | The hostname that will be used for accessing the server. |
NO_USE_SSL | If set, nginx will not listen on HTTPS (port 443) | |
CONVERTER_RESOLVER | 127.0.0.11 | DNS server that will be used to resolve the converter container's hostname. For Docker this should be 127.0.0.11, or for Kubernetes kube-dns.kube-system.svc.cluster.local. |
Document Conversion (securecircle-converter)
This container converts a variety of documents to PDF for use in SecureSend's View feature. If this container is not available, and the server is not given the correct converter_url, the Sharing Portal will not display the View option to recipients.