Self-Hosting

One of RocketShipIt's greatest advantages over our competitors is that it can be self-hosted on your own servers. This means that you and your customer's data is never shared, API request times are much faster, and you never have to worry about RocketShipIt's servers going down and interrupting business critical operations.

RocketShipIt comes with two major ways to self-host:

  1. HTTP JSON API
  2. stdin/stdout JSON directly to the RocketShipIt binary

HTTP JSON API

You can run RocketShipIt as an HTTP server/service in your own project's infrastructure. Just run the RocketShipIt binary with the -s flag, no installation or dependencies are needed.

By default, the server runs on port 8080 you can change this with the -p flag. The endpoint for all requests will be at http://localhost:8080/api/v1/

To authenticate with the RocketShipIt HTTP JSON API you need to set the RS_API_KEY environment variable and use that value as the username in HTTP Basic Auth. Leave the password blank. Example: RS_API_KEY=MySecretAPIKey ./RocketShipIt -s. Setting this environment variable will also require authentication for the API explorer.

Logging & Debugging

In server mode RocketShipIt logs only errors, and it writes them to a log.log file in the executable's directory — not to stdout or your service logs. Successful requests are not logged, and request/carrier data is never written to disk. To inspect exactly what RocketShipIt sent to and received from a carrier, use the debug parameter, which returns that information in the API response. See Logging & Debugging for the full details.

stdin/stdout

If you don't want to run an HTTP server you can also use the RocketShipIt binary as a simple input/output via stdin/stdout.

Just simply copy all the files to your project and make requests with one of the supporting clients in PHP, Ruby, Python, or JavaScript.

Or send JSON directly via stdin:

echo '{"your_json_request":"goes_here"}' | ./RocketShipIt

Setting up RocketShipIt as a Service on Linux

If you would like the RocketShipIt HTTP JSON API to run 24/7 and automatically start on boot you will need to create a service script. This tutorial targets systemd which is the default for most Linux distributions.

Create file: /lib/systemd/system/rocketshipit.service:

[Unit]
Description=RocketShipIt

[Service]
Type=simple
Restart=always
RestartSec=5s
# change to match your path
ExecStart=/home/mark/RocketShipIt -s

[Install]
WantedBy=multi-user.target

Start the service:

sudo service rocketshipit start

Start on boot:

sudo service rocketshipit enable

Check service status:

sudo service rocketshipit status

Restart the service:

sudo service rocketshipit restart

Legacy SystemV for CentOS6

Use this script if you are using an older version of CentOS or SystemV:

#!/bin/bash
#
# /etc/init.d/rocketship
#
# Starts the RocketShipIt API Service
#
# chkconfig: 345 95 5
# description: Runs the RocketShip.IT Local API Service on Port 18080.
# processname: rocketship

# Get function from functions library
. /etc/init.d/functions

# Start the service
start() {
echo "starting rocketship API service"
export RS_API_KEY="XXXXX"
export RS_UPS_KEY="XXXXX"
export RS_UPS_USERNAME="XXXXX"
export RS_UPS_PASSWORD="XXXXX"
export RS_UPS_ACCOUNT_NUMBER="XXXXX"
export RS_FEDEX_ACCOUNT_NUMBER="XXXXX"
export RS_FEDEX_METER_NUMBER="XXXXX"
export RS_FEDEX_KEY="XXXXX"
export RS_FEDEX_PASSWORD="XXXXX"
echo "Starting RocketShipIt server:" | /bin/logtimeadd.sh >> /var/log/RocketShipIt.log
/usr/local/rocketship/RocketShipIt -s -p 18080 >> /var/log/RocketShipIt.log 2>&1 &
sleep 2
echo "RocketSHipIt Started with PID of $(ps fax | grep RocketShipIt | grep -v grep | head -1 | awk '{print $1}')"
echo "RocketShipIt Started ["$(tput setaf 2)OK$(tput sgr0)"]"
### Create the lock file ###
touch /var/lock/subsys/RocketShipIt
success $"RocketShipIt server startup"
echo
}

# Restart the service RocketShipIt
stop() {
echo "Stopping RocketShipIt server:" | /bin/logtimeadd.sh >> /var/log/RocketShipIt.log
killproc RocketShipIt
### Now, delete the lock file ###
rm -f /var/lock/subsys/RocketShipIt
echo
}

### main logic ###
case "$1" in
start)
start
;;
stop)
stop
;;
status)
status RocketShipIt
;;
restart|reload|condrestart)
stop
start
;;
*)
echo $"Usage: $0 {start|stop|restart|reload|status}"
exit 1
esac

exit 0

Setting up RocketShipIt as a Service on Windows

At this time RocketShipIt can't natively be installed as a Windows host using typical tools like sc.exe. However, you can still install RocketShipIt as a Windows service using nssm.

Install the RocketShipIt service with nssm install command.

For more details see: https://nssm.cc/usage

Running RocketShipIt with Docker

Important: Mount Your License File as a Volume

When RocketShipIt starts and your license is due for a check-in, it contacts the license server and rewrites your license.lic file with an updated one. This is how license renewals and extended expiration dates reach your installation.

A container's filesystem is ephemeral: any file copied or baked into the image (e.g. with a COPY license.lic . instruction in a Dockerfile) is reset to the original stale copy every time the container is recreated — after a docker pull, a redeploy, or an orchestrator rescheduling the container. Eventually that stale baked-in license expires and RocketShipIt stops working, even though your account is active.

To avoid this, always bind-mount license.lic from the host (or a persistent volume), read-write, so license updates persist across container restarts and rebuilds:

-v /full/path/to/license.lic:/license.lic
  • Do not COPY the license into the image.
  • Do not mount it read-only (:ro) — RocketShipIt needs to write the updated license back to the file.
  • The license must be mounted into the same directory as the RocketShipIt binary (/license.lic for the official image, since the binary is at /RocketShipIt).

If you are on a platform where mounting a writable file is not practical (AWS ECS/Fargate, Kubernetes, etc.), use the RS_LICENSE environment variable instead.

Using the Official RocketShipIt Docker Image

You can always stay up to date with our official RocketShipIt Docker image:

docker run -v /full/path/to/license.lic:/license.lic -p 8080:8080 rocketshipit/rocketshipit:latest /RocketShipIt -s

The -v /full/path/to/license.lic:/license.lic part is required — see Mount Your License File as a Volume above.

To update:

docker pull rocketshipit/rocketshipit:latest

Show the version you have:

docker run rocketshipit/rocketshipit:latest /RocketShipIt -v

RocketShipIt Shipping API
Version:      2.8.1.706
Build Hash:  e256b36ff6a988ea98ea72a4046dbdef54e48e32
Build Time:  2022-06-29_03:00:23PM_UTC
Copyright (c) 2008-2022 RocketShipIt Inc. All Rights Reserved

Building your own Docker Image

Put your rocketshipit.tar.gz file in the same folder as your Dockerfile.

Do not copy license.lic into the image — mount it as a volume at run time instead, so RocketShipIt can update it and it survives container rebuilds (see Mount Your License File as a Volume above).

Create a Dockerfile:

FROM debian:buster

RUN mkdir -p /rocketshipit

WORKDIR /rocketshipit

COPY rocketshipit.tar.gz .

RUN tar -xzf rocketshipit.tar.gz && rm rocketshipit.tar.gz
RUN apt-get update
RUN apt-get -y install ca-certificates

COPY rocketshipit-entrypoint.sh /usr/local/bin/

RUN chmod +x /usr/local/bin/rocketshipit-entrypoint.sh

EXPOSE 8000

ENTRYPOINT ["rocketshipit-entrypoint.sh"]

Create rocketshipit-entrypoint.sh:

#!/bin/sh

/rocketshipit/RocketShipIt -s -p="8000"
  • Build container: docker build -t rs .
  • Run container: docker run -v /full/path/to/license.lic:/rocketshipit/license.lic -p 8000:8000 rs

Note that the license is mounted into /rocketshipit/, the same directory as the RocketShipIt binary.

Running on AWS ECS, Fargate, and Kubernetes: the RS_LICENSE Environment Variable

Requires RocketShipIt 2.8.2.349 or newer.

On orchestrated container platforms there is often no host filesystem to bind-mount a license file from — AWS Fargate in particular only supports EFS volumes. For these environments, RocketShipIt can take its license from the RS_LICENSE environment variable instead of a license.lic file.

Set RS_LICENSE to the full contents of your license.lic file (the -----BEGIN ROCKETSHIPIT LICENSE KEY----- block, exactly as downloaded — do not alter whitespace or line breaks). When no license.lic file is found next to the binary, RocketShipIt:

  1. Validates the license from RS_LICENSE (it is cryptographically signed, so it cannot be tampered with).
  2. Checks in with the license server at startup and fetches your current license.
  3. Keeps the updated working copy in the container's tmp directory.

Because every new container/task checks in at startup, license renewals are picked up automatically — you set RS_LICENSE once and new tasks always start with your current license. There is nothing to persist across container replacements.

A license.lic file mounted next to the binary always takes precedence over RS_LICENSE, so existing setups are unaffected.

AWS ECS Setup

Don't put the license directly in the task definition's environment block — store it in AWS Secrets Manager (or SSM Parameter Store) and let ECS inject it:

  1. Store the license:
aws secretsmanager create-secret \
  --name rocketshipit-license \
  --secret-string file://license.lic
  1. Reference it in your task definition's container definition:
{
  "name": "rocketshipit",
  "image": "rocketshipit/rocketshipit:latest",
  "command": ["/RocketShipIt", "-s"],
  "portMappings": [{ "containerPort": 8080 }],
  "secrets": [
    {
      "name": "RS_LICENSE",
      "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:rocketshipit-license"
    },
    {
      "name": "RS_API_KEY",
      "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:rocketshipit-api-key"
    }
  ]
}

Your task execution role needs secretsmanager:GetSecretValue permission on the secret (or ssm:GetParameters if you use a Parameter Store ARN in valueFrom).

  1. When you renew your license, update the stored secret with your newly downloaded license.lic:
aws secretsmanager put-secret-value \
  --secret-id rocketshipit-license \
  --secret-string file://license.lic

This last step is a safety net: tasks fetch the current license from the license server at startup anyway, but if the license server is ever unreachable when a task starts, RocketShipIt falls back to the RS_LICENSE value.

On Kubernetes the same pattern applies: store the license in a Secret and expose it to the container as the RS_LICENSE environment variable via env[].valueFrom.secretKeyRef.

Older RocketShipIt versions on ECS

If you can't upgrade to a version with RS_LICENSE support:

  • EC2 launch type: bind-mount the license file from the host like a normal Docker volume (a volumes entry with host.sourcePath pointing at the file, mounted at /license.lic).
  • Fargate: mount an EFS volume read-write and place both the RocketShipIt binary and license.lic in the same directory on it (e.g. mount EFS at /rocketshipit and set the command to /rocketshipit/RocketShipIt -s). The binary must live on the volume too because RocketShipIt looks for — and writes — license.lic in its own directory, and an EFS mount would otherwise hide a baked-in binary at that path.

Connect to container for troubleshooting:

docker exec -it <your_container_id> /bin/bash

Errors will be logged in log.log. See Logging & Debugging for what is and isn't logged.

Does RocketShipIt Send Data Home?

Yes, when using RocketShipIt self-hosted or on-premise, we collect a minimum amount of information to help improve the product. This information is used to inform us which users are actively using RocketShipIt, which version is being used, how many API requests are made, and if RocketShipIt is using too much memory or crashing.

We do NOT collect any carrier request or response information other than the number of requests made. We cannot see you or your customer's data.

Sample of data sent to RocketShipIt:

{
    "started_at": "2020-04-22T14:46:01.835246057-04:00",
    "ended_at": "2020-04-22T14:56:01.496260187-04:00",
    "api_total_requests": 1033,
    "os_type": "linux",
    "app_mem_usage": 10823968,
    "app_mem_total_usage": 735226600048,
    "app_uptime": 689400,
    "app_version": "2.8.1.351",
    "user_id": "abcdefg123",
    "version": "1"
}
← ErrorsLogging & Debugging →