Getting started
Hardware & Network requirements
To run SingleJump, you need to have a physical server or a virtual machine with the following minimum hardware requirements:
- 2 CPUs
- 4GB of RAM
- 60GB of disk space
Additionally, it is recommended that you have a static public IP address so that this IP address can be the one accepted in the firewalls of your devices.
If you are planing to generate Let’s Encrypt certificates to secure the web access, the TCP port 80 should be opened.
Prepare your system
Install docker & docker compose
On Debian/Ubuntu systems:On RPM-based distributions:
Create directory structure
SingleJump will persist data in the directories that you specify in the .env file, but you also need to create the directory structure for those volumes. For example:
mkdir -p /opt/singlejump/data/mysql/ /opt/singlejump/data/keys/ /opt/singlejump/data/recordings/ /opt/singlejump/data/logs/ /opt/singlejump/data/certs/ /opt/singlejump/data/letsencrypt/etc/ /opt/singlejump/data/letsencrypt/var/ /tmp/letsencrypt
DNS setup
It is recommended to choose a subdomain to access your SingleJump instance, as this will allow for the installation of an SSL certificate. For example: login.singlejump.com
To do this, point the subdomain using an A record to the IP address you have chosen for your SingleJump instance.
Install SingleJump
Authentication
SingleJump utilizes a private Docker repository to store the Docker images (web_server and ssh_server). To access these images, authentication with our repository is required.
To authenticate, follow these steps:
And provide your credentails.
Create Compose File
Navigate to the directory where you are setting up SingleJump, such as /opt/singlejump, create a new file called docker-compose.yml with the following content:
version: "3.8"
services:
web_server:
container_name: web_server
image: docker.singlejump.com/web-server:1.0
environment:
- TIMEZONE=${TIMEZONE}
- DB_DATABASE=${DB_DATABASE}
- DB_USERNAME=${DB_USERNAME}
- DB_PASSWORD=${DB_PASSWORD}
- DB_KEY=${DB_KEY}
- DOMAIN=${DOMAIN}
ports:
- ${HTTPS_PORT}:443
- 80:80
volumes:
- ${VOLUME_KEYS}:/home/singlejump/webapp/storage/app/keys
- ${VOLUME_RECORDINGS}:/home/singlejump/recordings
- ${VOLUME_LOGS}:/home/singlejump/webapp/storage/logs
- ${VOLUME_CERTS}:/home/singlejump/webapp/storage/app/certs
restart: unless-stopped
ssh_server:
container_name: ssh_server
image: docker.singlejump.com/ssh-server:1.0
environment:
- DB_DATABASE=${DB_DATABASE}
- DB_USERNAME=${DB_USERNAME}
- DB_PASSWORD=${DB_PASSWORD}
- DB_KEY=${DB_KEY}
ports:
- ${SSHD_PORT}:2222
volumes:
- ${VOLUME_KEYS}:/home/singlejump/keys
- ${VOLUME_RECORDINGS}:/home/singlejump/recordings
- ${VOLUME_LOGS}:/home/singlejump/logs
restart: unless-stopped
database_server:
container_name: database_server
image: mysql:latest
ports:
- 3306
volumes:
- ${VOLUME_MYSQL_DATA}:/var/lib/mysql
environment:
- MYSQL_RANDOM_ROOT_PASSWORD=yes
- MYSQL_DATABASE=${DB_DATABASE}
- MYSQL_USER=${DB_USERNAME}
- MYSQL_PASSWORD=${DB_PASSWORD}
restart: unless-stopped
Now we need to configure our docker-compose environment variables. To do that, we need to generate a key that will be used to secure some user information into the database. You can generate it with the following command:
Please take note of the output and use that string to set the variable DB_KEY in your .env file.
Also, ensure to set a secure password in the DB_PASSWORD variable.
Avoid using characters such as &, |, ;, <, >, !, [, ], (, ), {, }, *, ?, $, #, ^, ~, ", ', or ` in your DB_PASSWORD variable, as they may cause unexpected behavior.
Create the environment variables file .env and populate it with your configuration:
# Enviroment variables for running docker instances
TIMEZONE=America/Chicago
DB_DATABASE=singlejump
DB_USERNAME=singlejump
DB_PASSWORD=(random_password)
# You can generate this key with the following command: dd if=/dev/urandom bs=32 count=1|base64, do not change it after set
DB_KEY=(database_password_please_change)
HTTPS_PORT=8585
SSHD_PORT=2023
DOMAIN=login.yourdomain.com
VOLUME_KEYS=/opt/singlejump/data/keys
VOLUME_RECORDINGS=/opt/singlejump/data/recordings
VOLUME_LOGS=/opt/singlejump/data/logs
VOLUME_CERTS=/opt/singlejump/data/certs
VOLUME_MYSQL_DATA=/opt/singlejump/data/mysql
Set your license file
Place the provided license.txt file into the directory data/keys, for example: /opt/singlejump/data/keys/license.txt.
Start your SingleJump
Now it's time to start SingleJump. You can run your docker-compose file with the following command:
Configure SingleJump
SingleJump comes without any user, before you can access it you need to create a super-admin user.
Create super-user
Execute the following command and follow the instructions:
docker exec -it web_server su - singlejump -c "php /home/singlejump/webapp/artisan make:super-admin"
Login to the web interface
Now you can log in to the web interface using your IP address or domain specified in the .env file. For example: https://login.yourdomain.com:8585. Use the super-user credentials previously created.
Secure your web interface
We recommend setting up SSL to access your web interface, and you have two options:
Use Let’s Encrypt certificates
We shipped SingleJump with Let’s Encrypt auto signing and renewal for SSL certificates.
To generate and sign your Let’s Encrypt certificate, please follow these steps:
- Go to Settings.
- Enter your email address and domain name (e.g., login.yourdomain.com).
- Click Enable, then Save.
- Click Request, then Request now.
Please ensure that TCP port 80 is opened in your firewall and a public IP address is configured on your server to sign your certificate.
SingleJump will automatically renew the certificate before it expires.
Initialize the database
SingleJump utilizes asymmetric encryption or public-key encryption to store SSH private keys for each device you add. To do this, you need to generate the master private/public key that will be used for all your devices and users.
Please note that you should only initialize the database once. If you do it more than once, you will lose access to your devices, and you will have to add them again.
To initialize the database, enter your super-admin user password and click Save.
Activate your Two-Factor Authentication
To access devices through SSH or view SSH session recordings, you should enable 2FA. Currently, SingleJump provides Google Authenticator, but more alternatives will be added.
To enable it, click on the profile button at the top right corner, then click on "Two Factor Authentication", and then click "Enable".
You will be prompted for your password and presented with a QR code that you can scan using the Google Authenticator app.
Now you can start adding your Device Groups, Devices and Users.
Enable SSH Access
SingleJump allows SSH access to your devices through two methods:
From your browser by accessing the SingleJump web interface. From your favorite SSH client like Putty or the regular SSH terminal client. By default, there is an ACL (Access Control List) that allows connections from anywhere (0.0.0.0/0) for web access, but SSH access to SingleJump is disabled.
We recommend changing this default ACL to include only the IP address from which you or your staff will connect, and enabling SSH access. This will allow you to use SingleJump SSH Server to access your devices.
To do so, connect to SingleJump like this:
ssh -l [email protected] -p2023
You can add as many ACLs as you want, including IP addresses or networks. You can also define those ACLs by user or globally.
Please note that you need to enable Two-Factor Authentication before connecting to SingleJump via SSH.