Sign in

Quick start

Last updated on 
Quick start

Would you like to apply docker to various remote daemons, as you can for k8s? Well:

smr apply https://raw.githubusercontent.com/simplecontainer/examples/refs/heads/main/tests/minimal/definition.yaml
smr ps
NODE             GROUP    NAME     DOCKER NAME        IMAGE           IP                   PORTS  DEPS  ENGINE STATE      SMR STATE        
smr-agent-2 (2)  example  busybox  example-busybox-1  busybox:latest  172.17.0.4 (bridge)  -      -     running (docker)  running (1m18s)  
smr-agent-2 (2)  example  busybox  example-busybox-2  busybox:latest  172.17.0.5 (bridge)  -      -     running (docker)  running (1m18s)

Voila! This is a quick start tutorial for how you can do just that.

Installation

Using smrmgr

The smrmgr is bash script for management of the simplecontainer. It is used for:

  • Downloading and installing client
  • Starting the node in single or cluster mode
  • Starting the node and joining to the existing cluster
  • Various options and configuration simplified
curl -sL https://raw.githubusercontent.com/simplecontainer/smr/refs/heads/main/scripts/production/smrmgr.sh -o smrmgr
chmod +x smrmgr
sudo mv smrmgr /usr/local/bin
sudo smrmgr install

Using smr

The smr is a client used to communicate to the local/external simplecontainer agents running on nodes. The smrmgr automatically downloads the client and places it under /usr/local/bin/smr.

To manually install, start, and manage simplecontainer nodes download the client from the releases:

https://github.com/simplecontainer/client/releases

LATEST_VERSION=$(curl -s https://raw.githubusercontent.com/simplecontainer/client/main/version)
PLATFORM=linux-amd64
curl -o client https://github.com/simplecontainer/client/releases/download/$VERSION/client-$PLATFORM
sudo mv client /usr/local/bin/smr

Explore /scripts/production/smrmgr.sh to see how you can utilize smr client to configure and start simplecontainer nodes.

Running simplecontainer

The simplecontainer can be started in a single node mode or cluster mode.

Cluster mode

Simplecontainer can run in single and cluster mode. Cluster mode allows users to deploy Docker daemons on different hosts and connect them via simplecontainer. An overlay network is created using flannel to enable inter-host communication.

Simplecontainer uses RAFT protocol to enable distributed state using the Badger key-value store. Etcd embedded is also started in single mode and exposed to localhost only without credentials. Flannel uses only Etcd as the state store for the network configuration.

Control-plane and RAFT communication is secured using mTLS so data is encrypted even over non-secure underlying networks.

Ports exposed:

  • 0.0.0.0:1443->1443/tcp (The simplecontainer control plane)
  • 0.0.0.0:9212->9212/tcp (The RAFT protocol control plane sharing state)
  • :::1443->1443/tcp (The simplecontainer control plane ipv6)
  • 127.0.0.1:2379->2379/tcp (The etcd exposed only on the localhost)

How to run it?

This scenario assumes there are two nodes(virtual machines) connected over a non-secure internet connection.

  • Node 1: node1.simplecontainer.com -> Points to Node 1 IP address
  • Node 2: node2.simplecontainer.com -> Points to Node 2 IP address
Node 1

Requirements:

  • The smgrmgr already installed
  • The docker daemon running on the Node 1
smrmgr start -a smr-agent-1 -d smr1.example.com -n node1.example.com
# Copy the content of the export
smrmgr export https://node1.example.com:1443
# Copy the decryption key
cat $HOME/smr/smr/contexts/$(smr context).key
Node 2

Requirements:

  • The smgrmgr already installed
  • The docker daemon running on the Node 2
smrmgr import {{ PASTE CONTEXT }} <<< {{ PASTE KEY }}
smr context fetch
smrmgr start -a smr-agent-2 -d smr2.example.com -n node2.example.com -j node1.example.com:1443

Afterward, the cluster is started. Badger key-value store is now distributed using RAFT protocol. Flannel will start and the agent will create a docker network named cluster.

To connect containers with cluster network in the container definition specify that you want the container to connect to the cluster network.

Single node mode

The simplecontainer can also be run as a single node without clustering enabled and additional overhead if it is not mandatory to have multiple nodes, high availability, and disaster recovery in place for the application.

The control plane can be exposed:

  • On the localhost only to prevent control plane communication from being done outside localhost
  • On the 0.0.0.0:1443 which means all interfaces that include all endpoints localhost or from another network.

How to run it? (Control plane exposed to all networks)

Exposing the control plane to the `0.0.0.0:1443` and smr.example.com will be only valid domain for the certificate authentication (Change smr.example.com to your domain).

smrmgr start -a smr-agent-1 -d smr.example.com
# Copy the content of the export
smr context export <<< https://smr.example.com:1443
# Copy the decryption key
cat $HOME/smr/smr/contexts/$(smr context).key

On the external machine run:

smr context import {{ PASTE CONTEXT }} <<< {{ PASTE KEY }}
Providing domain and IP address for the certificates

Domain and IP addresses are provided for the simplecontainer to generate certificates. Certificates will be valid for domains and IP addresses specified.

Another way of exposing the simplecontainer control plane is via IP address.

smrmgr start -a smr-agent-1 -d smr.example.com -i 1.1.1.1

Starting this way the certificates will be valid for the:

  • Domain: smr.example.com
  • IP address: 1.1.1.1

How to run it? (Control plane exposed to the localhost only)

Exposing the control plane only to the localhost:

smrmgr start -a smr-agent-1 -e localhost:1443

This way smr CLI can only talk to the simplecontainer via localhost.

Contexts

Context is holding certificates, keys, control plane URL, and name of the agent. They are used for authentication against the simplecontainer.

The authentication is done via mTLS using certificates when simplecontainer node is started certificates are generated under ~/.ssh/simplecontainer. Certificates for the smr CLI are bundles as .pem file with name of the agent that is running it.

There are a few commands to help out while using smr CLI:

sm context export

smr context export <<< https://smr.example.com

This command is used for the exporting of the current context for external usage. It exports context encrypts it and saves the encryption key at

$HOME/smr/smr/contexts/$(smr context).key

This can used later for importing.

Can be utilized for distributing contexts for developers or as a service account for machine authentication.

smr context import

smr context import {{exported}} <<< {{key}}

This command is used for the importing the exported context. Afterward, smr CLI can be used for communication to the external simplecontainer.

smr context switch

smr context switch

This command is used for switching the current context so you can communicate with different simplecontainer nodes.

Another form is smr context switch {{name}} where name is the name of the agent.

smr context connect

smr context connect https://localhost:1443 $HOME/.ssh/simplecontainer/root.pem --context smr-agent-1

This command is used for connecting to the simplecontainer node when .pem bundle is present on the local machine - this is mainly used on the localhost when starting the simplecontainer node.

Otherwise it is recommended to use context and import.

smr context

smr context

This command prints out the current context.

Next steps?

This is quick introduction into starting simplecontainer nodes in single or cluster mode.

Next steps:

GitOps with Docker
Simplecontainer enables the GitOps approach to deploying containers on single or multiple simplecontainer hosts. This allows the simplecontainer to pull the latest changes on the definitions from the git repository instead of pushing the changes to the simplecontainer via CLI. First, you need to have simplecontainer running and CLI configured
SimplecontainerAdnan Selimovic