Sailor

Sailor is a command line tool for deploying local code to a stack in a remote Portainer instance. Simply authenticate with the target Portainer instance and choose the stack and service to update. The local project is packaged and uploaded, the image is built on the remote server, and the stack is updated to use the new image.

This tool was heavily inspired by CapRover's CLI and is intended to be an alternative for users who run Docker Compose instead of Docker Swarms. As an example, this is more ideal for self-hosting small projects on a Raspberry Pi or NAS that need access to hardware or advanced network configurations.

Installation

Install the command line tool using npm. If interested, you can also view the package on npm.

npm install -g @baileyherbert/sailor

Adding servers

The very first thing you need to do is register and log into a Portainer instance. You can add an unlimited number of instances, and will be able to choose between them when deploying. Run the following command and follow the prompts:

sailor add

You will be asked to provide a URL to the Portainer instance and give it a local nickname. Then, you will choose between logging in using an access token or with a username and password. If you log in with a password, Sailor will automatically create an access token for you, and will only store the resulting token.

If the target server uses a self-signed or untrusted SSL certificate, Portainer will display the certificate details and ask if you would like to permanently trust the certificate. This will also occur later, such as during deployments, if the certificate changes.

Make sure that the access token or user account you sign into has privileges to access and modify the target stack.

Deployments

Run the following command to start a deployment:

sailor deploy

You will be guided through a series of prompts to configure the deployment:

1. Choose a target server. If you don't see yours in the list, run sailor add first.
2. Choose the target endpoint. This step is only shown if the Portainer instance is connected to multiple environments.
3. Choose the target service. This lists all available services across all stacks, and shows their current image tag.
4. Enter the name of the target branch (git). The current active branch is suggested automatically for convenience.

After this, the project is tarballed, uploaded to the server, built, and deployed to the specified service. For more details on how this works, see the next section.

Sailor remembers all of the configuration you enter in the steps above for the current directory. Next time you want to deploy the same project, pass the -d parameter to automatically load the saved configuration:

sailor deploy -d

How deployments work

Sailor deploys projects in a nearly identical manner to the CapRover CLI. There are some important things to know about this process.

First, deployments must occur in the root directory of a Git project. When deploying, Sailor will prompt for a target branch name. It will also check and suggest the current active branch name for convenience.

After confirming the target branch, Sailor tarballs the project's files directly from the latest commit in that branch, and uploads it to the remote Docker API through Portainer for building. Uncommitted files are never included in the tarball.

Sailor will attempt to show live logs from the build. However, due to buffering on Portainer's side, the logs will only update periodically until the build completes. If the build fails, Sailor will report the error and exit with an erroneous exit code.

The project is expected to have a Dockerfile in the root directory. And because the image is built on the target server, the resulting image automatically supports the target platform and architecture.

Other commands

• sailor list – Lists registered servers
• sailor remove – Allows you to choose a server to delete

Debugging

If you're having trouble with a command, try passing the -v flag to enable verbose logging. Note that this must be passed before the subcommand because it is a global flag.

sailor -v add
sailor -v deploy

Storage

Sailor uses configstore to save server and deployment configuration. The following paths are generally used:

Linux and macOS

~/.config/configstore/sailor.json

Windows

C:\Users\<username>\.config\configstore\sailor.json