Quick start¶

Dependencies¶

1. Clone Git repository¶

$ git clone git@github.com:includeos/mothership-beta.git

To clone using a specified unique ssh key:

$ ssh-agent bash -c 'ssh-add mothership_beta.key; git clone git@github.com:includeos/mothership-beta.git'

2. Create user¶

Mothership comes with basic authentication enabled by default. It is therefore necessary to create a user:

$ touch config_files/.htpasswd               # Create empty .htpasswd file
$ htpasswd -B config_files/.htpasswd myuser  # Add the user myuser

3. Configure TLS¶

TLS is also enabled by default. Mothership expects two files to be present in the folder config_files:

cert.pem:	File containing your certificate
key.pem:	File containing your private key

For instructions on how to generate a self-signed certificate for testing see: Create self-signed TLS certificate

4. Build and launch Mothership¶

First build then then run mothership using docker:

$ docker build -t mothership .
$ docker run \
    --name mothership \
    -p 8080:8080 \
    -p 9090:9090 \
    -v $PWD/config_files:/home/ubuntu/mothership/config_files \
    -v mothership_storage:/home/ubuntu/mothership/runtime_files \
    -v /var/run/docker.sock:/var/run/docker.sock \
    mothership serve

The options used are:

First are the docker options:
    --name mothership                   Give docker container name
    -p 8080:8080                        Forward port 8080
    -p 9090:9090                        Forward port 9090
    -v $PWD/config_files:/home/ubuntu/mothership/config_files   Bind-mount config_files folder into mothership
    -v mothership_storage:/home/ubuntu/mothership/runtime_files Mount named volume into mothership
    -v /var/run/docker.sock:/var/run/docker.sock  Mount hosts docker process into container
Then the mothership options:
    mothership serve                    Start mothership server

Note

If you are experiencing problems with permissions for the mounted resources you might need to launch the docker container with --privileged. On systems like RedHat Enterprise Linux that use SELinux this might be necessary. This will need to be sent to the inside as well by using --dockeroptions "--privileged" as a Mothership option as well.

This will launch the mothership server. Make sure there are no errors in the launch output and the following lines indicate that basic auth and TLS are properly configured:

INFO[0014] 1 registered user
INFO[0014] Setting up hangar (uplink) with TLS on :9090
INFO[0014] Setting up server with TLS on :8080
⇨ https server started on [::]:8080

5. Access Mothership¶

There are three ways to interact with the Mothership server.

Web GUI: This GUI is available at: https://localhost:8080, for more information on this please see: Mothership GUI
API: For more information on the various API endpoints, see the API documentation at https://localhost:8080/apidocs/apidocs.html
Command-line interface: The binary mothership-linux-amd64 used to launch the server also works as a CLI

Using the CLI the following command will give you information about the running instances:

$ ./mothership-linux-amd64 --username <username> --password <password> instances
Instances:
Alias  Status  ID  Image Tag  Launched