Flockport currently supports the following distributions
You can check the support matrix to see all supported OSs
Download the installer from the downloads page and extract it.
tar -xpzf flockport-0.9.tar.gz
cd into the flockport folder and run install.sh. Please note you need to be root to install Flockport. On Alpine Linux please ensure bash is installed before running the installer.
./install.sh
This will automatically detect the OS and install Flockport and required packages.
Once installed you can run the help command to get a summary of available commands
flockport help
Running a subcommand provides usage information for the command
flockport run
A default Alpine Linux container is included to help you get started.
We will use c1 and c2 as example container names in the sections below.
Use the ls command to list all containers on your system.
flockport ls
This will list all containers.
To get an overview of runtime information of containers use the ps command.
flockport ps
This will list all running containers.
To get more detailed information on the container use the info command.
flockport info c1
This will display detailed information on the c1 container.
You can start a container with the start command
flockport start c1
This will start the c1 container.
You can now run ps or info to get live stats and detailed run time information on c1
flockport info c1
You can stop c1 with the stop command.
flockport stop c1
This will stop the c1 container.
You can access a running container with the attach command.
flockport attach c1
This will drop you into a shell in the container. You can run commands in the container and the environment is identical to an OS like a VM. Use the exit command to exit the container shell.
You can directly execute commands on the container with the exec command.
flockport exec c1 ifconfig
This will run ifconfig in c1 and list network interfaces present in the c1 container.
Containers can be deleted with the rm or remove command
flockport rm c1
This will delete the c1 container. Note incase the c1 container has snapshots the delete will fail. You can only delete containers that have snapshots once all the snapshots have been deleted
Containers run in an internal network that can only be accessed by other containers and the host. We will cover this in more depth in the container networking section.
To make any applications running in containers available to the outside world you need to forward container ports to the host. With port forwarding any system that can access the host can access the container on the forwarded port.
You can use the flockport pub command to forward ports
flockport pub c1 80:80
This forwards container c1's port 80 to host port 80. Similarly
flockport pub c1 80:3000
This forward c1's port 80 to host port 3000. You can also simply run
flockport pub c1 80
This forwards c1's port 80 to host port 80
To stop port forwarding run
flockport unpub c1 80:80
This will stop the port forwarding to the host.
If you forwarded the same port
flockport unpub c1 80
You can use the ps or info command to get an overview of forwarded ports
flockport info c1
When you stop a container any forwarded ports are automaticaly stopped. To ensure ports are published on container startup use the autoports command
flockport autoports c1 on 80:80
This will ensure c1 port 80 is published to host port 80 on container start
Similarly to disable auto port forwarding
flockport autoports c1 off 80:80
Volumes are a way to share host data with the container or separate any state data from the container. This is done so the container only holds the application and the application data is kept elsewhere.
You are perfectly free to store data in the container like a VM and the data is safe untill you delete the container.
Flockport is not opinionated on how to architect or deploy your application. Statelessness is a function of application design and architecture.
We give you the tools to build both stateless and stateful containers.
To share a host folder with a container
flockport attachvol c1 /var/www/web
This makes /var/www/web on the host available on the container
You can also use a container volume. A container volume is a container that shares a specific folder within itself with other containers.
You can create a container volume by using the createvol command. Simply specify a name for the container volume and a shared folder.
flockport createvol mysql /var/lib/mysql
This creates a 'mysql' container volume on your system with a /var/lib/mysql shared folder in the container.
Now you can share the mysql container volume with any other container and they will share the /var/lib/mysql folder of the 'mysql' container.
flockport attachvol c1 mysql
This will attach the mysql container volume to c1 and the /var/www/mysql folder specified when creating the container volume will be shared with c1
You can use the listvolumes command to list all container volumes
flockport listvolumes
This will list all container volumes on the host along with their shared dirs
You can use the info command to get an overview of all attached volumes or in the case of container volumes shared directories
flockport info c1
The benefit of using container volumes as opposed to a folder on your host is portability. The main advantage of containers is portability across systems. Tying data to the host takes away one of the core benefits of containers as opposed to container volumes that can be moved across servers seamlessly.
The Flockport App Store provides base os images, dev runtimes and applications. To list all available images.
flockport images
Thus will list all images available in the app store. To download images use the get command.
flockport get xenial
This will download the xenial baseimage and make it available for use on your local system.
All Flockport images are signed and downloaded securely. You need a Flockport ID to download images. The same id will be used for other services including signing in to the Flockport forums.
You can register from the Flockport app.
flockport register
This will prompt you for a username, password and email and create a flockport account.
Once registered you can login in with your username and password.
flockport login
This will prompt you for your username and password and generate an auth token. Once logged in you can download images.
flockport get xenial
Once downloaded you can 'run' or 'start' the xenial image.
flockport run xenial
This will launch a copy of the xenial image ready for use.
run launches a copy of an image. start starts the actual container image. So if you start the xenial image any changes remain in the image.
When you launch an image with the run command you ensure the original image remains untouched.
When you use the run command Flockport launches a copy of the container. Flockport uses overlayfs to launch a snapshot of the image. The name of the new container is autogenerated and can be specified with the -n flag
flockport run xenial -n myxenial
This will launch a copy of xenial with the name myxenial.
Please note the default Jessie kernel does not support overlayfs. Upgrading the Jessie kernel adds overlayfs support. When run detects overlayfs support is missing it makes a normal copy of the container. Similarly if the underlying filesystem is btrfs run will launch a btrfs subvolume clone
You can also download applications from the App store.
flockport get wordpress
This will download the wordpress application. Once downloaded you can run the wordpress image and access the application in your browser
flockport run wordpress
The will start a copy of the wordpress container under a random generated name. Applications are available on the container IP. You can point your browser to the container IP or container IP:PORT if the application is on a specific port to access the app
You can also forward the container port to the host and it will be available on the host IP. For instance
flockport pub wordpress 80
This will forward container port 80 to the host port 80. Now you can access the app on the host IP.
You can also forward ports when you start or run a container.
flockport run wordpress -p 80
This will forward port 80 to the wordpress container
Most apps will be available on the container IP. Some apps may require an URL. Apps are configured to be available at a default url ie myappname.org ie for Wordpress the url will be mywordpress.org.
On access most apps will take you to the setup screen. Any databases required are automatically created by Flockport. The password for apps to access the database is stored in the root folder of the container under .appname.pass ie for wordpress .wordpress.pass
There are exceptions with some Ruby and Go based apps. Please visit the forums for more detailed instructions.
Please note it's generally not a good idea to run databases like Mysql or Postgresql in layers for performance and stability reasons. When you download an image from the app store that is a database or has a database it's best practice to clone and 'start' it than 'run' it to avoid mixing up databases and layers.
To access an app by url instead of IP for instance mywordpress.org you need to associate the container IP with the url in your /etc/hosts file. You can retrieve the container IP with the ps or info command. You can edit the hosts file manual or use the addhosts command
flockport addhosts mywordpress.org [container IP]
When you need to forward multiple containers to the same port for instance host port 80 the Flockport managed web server becomes useful. This is an Nginx reverse proxy that you can use to easily serve multiple container applications.
You can make snapshots of containers with the snap command.
flockport snap c1 c2
This makes a snapshot of c1 as c2.
When you create a snapshot or run an image overlayfs is used in the background. Overlayfs let's you create a new filesystem with another filesystem as the base, basically mounting one filesystem over another, with all changes going to the new layer.
A snapshot container basically mounts a new layer over the baseimage. The base remain untouched while all changes go to the snapshot.
You can further make a snapshot of c2
flockport snap c2 c3
Each snapshot is a new overlayfs layer. For instance you can make a snapshot of a base OS image and add an application and then use that as an image to run the application.
Any changes goes to the new layer while the application layer remains untouched. You can update the base layer and it will show up in the new layer. Any updates to the base layer do not require a image rebuild.
An image and container is essentially the same thing. We only use the term image to refer to a container when it is used as a base to launch a new container.
You can get details on container layers with the history command.
flockport history c3
This will list the snapshot history of the c3 container. When used on a base image, history will show the list of snapshots made from the base image
You can also use the diff command to see changes in snapshotted containers
flockport diff c3 c2
This will list all the filesystem changes in c3 from c2
You can also clone containers
Cloning containers creates a copy of the container. Flockport supports btrfs and if the underlying filesystem is btrfs a subvolume clone is created.
flockport clone c1 c2
This makes a copy of c1 to c2.
Images can be exported and imported
flockport export c1
This exports c1 as a tar archive that can be imported on any flockport system. If the underlying image has overlayfs layers it's a good idea to use the merge option to create a single image before export
flockport export c1 -m
if c1 is a snapshot of for instance an alpine36 baseimage which exists on the new system then a merge is not required. But if the base layer is not present on the new system the c1 container will fail to start as as the underlying layer is missing.
The Flockport installer sets up a default bridge lxcbr0 with the 10.0.4.0/24 subnet. All containers are configured to connect to this bridge for their networking.
You can change the default 10.0.4.0/24 subnet with the setsubnet command.
flockport setsubnet 10.0.10.0/24
This will change the default subnet to 10.0.10.0 and containers will get an IP in the 10.0.10.0/24 range eg 10.0.10.40
You can also add new bridges with their own subnets and connect containers to them.
flockport addbr br0 -s 10.0.50.0/24
This will add a new network bridge br0 with subnet 10.0.50.0/24 to your host.
You can use the setnet command to connect individual containers to this new bridge
flockport setnet c1 eth0 br0
This will set the c1 container's network to the br0 bridge.
Containers can have multiple network interfaces. The default is eth0. You can add more interfaces. Each interface needs a corresponding bridge.
Multiple interfaces can link to the same host bridge or multiple bridges. This gives users significant flexibility in setting up their container networks
You can add a container network interface with the addnet command.
flockport addnet c1
This will add a new network interface to c1 container. Network interfaces are named in ascending order ie eth0, eth1
You can also specify a bridge with the -l flag when adding a network interface
flockport addnet c1 -l br0
This will add a network interface to c1 linked to br0 bridge
You can list container network interfaces with the listnet command
flockport listnet c1
This lists all network interfaces on the c1 container
You can set static IPs with the setip command. Please note the IP must be in the same subnet as the container's network.
flockport setip c1 10.0.4.10
This will set c1 eth0 interface IP to 10.0.4.10. You can revert to dhcp with
flockport setip c1 dhcp
To set IP for other interfaces specify them with a colon separator
flockport setip c1 eth1:10.0.4.10
This sets c1 eth1 interface IP to 10.0.4.10. To set the interface to dhcp
flockport setip c1 eth1:dhcp
This will set c1 eth0 interface back to default dhcp
You can delete network interfaces with the delnet command
flockport delnet c1 eth1
This will delete the eth1 network interface from c1
To delete a Flockport created bridge on the host use the delbr command
flockport delbr br0
When creating a network bridge a number of defaults are used. A DHCP service and masquerading to ensure containers on the bridge have outward internet access is enabled by default.
You can customise these options with relevant flags
flockport addbr br0 -s 10.0.50.0/24 -n -d domain
The -s flag sets the subnet range and must be in the x.x.x.x/xx subnet format ie 10.0.10.0/24. Masquerading is on by default. The -n flag sets masquerading for outward internet access for the br0 network interface off. The -d flag sets the domain. For instance the default flockport bridge is set to the '.app' domain. When you add a bridge you can set a specific domain for that network.
You can build containers with the flockport build command. Flockport uses recipes to build containers.
Flockport recipes are a set of instructions to build app containers. Recipes make it easy to define your applications for repeatable builds and create and share container based applications.
To build a container simply point it at a folder with a .recipe file.
flockport build wordpress
This will build a container as per the instructions found in the wordpress.recipe file.
Recipes should have the .recipe extension. Any supporting assets required for the container build ie configuration files, should be in the same folder.
The recipe format uses a few key words.
NAME minio50
FROM go18
ENV MINIO_HOME /opt/minio
COPY conf/json.conf /var/www/minio/json.conf
RUN apk add minio
VOLUME minio-data
PORT 9000
DB mysql minio minio
NAME defines the name of the container. If not provided a name is auto generated.
FROM defines the base image, it can be a base OS image, a language run time or any container you want to base your build on.
ENV defines any environmental variables to be set. These are available in the container at both build time and run time. They are saved. For build time env variables it's better to just use RUN. Remember to include the '=' when specifiying variables in RUN.
RUN MINIO_HOME=/opt/minio
COPY copies any assets and resources to the specified container folder. Any files to be copies must be in the recipe folder and path must be relative to the .recipe file.
RUN is a set of commands to run inside the container to process the build. You can use multiple RUN commands or separate them with a && and \\. RUN follows the semantics of Bash. Flockport does not use layers to build containers so you can use as many RUN commands as required or use a single one.
VOLUME is any container volume or host folder you want to attach to the container. In the case of a host folder you can specify the folder directly. In the example below we use a container volume. Volumes can also be specified at run time when running the container.
PORTS specifies any ports to be forwarded. In the example below we are forwarding port 9000 used by the Minio GUI. Ports specified in .recipe files are added as autoports so whenever the container is started the ports are automatically forwarded.
DB specifies any database required for the application. This allows you to directly create a database for an application. This accepts 5 options separated by single spaces. The first specifies the base db container name. The base db container must available on the local system. Only Flockport Mysql and Postgresql instances are supported for the DB option. The other 4 options specify the dbname, dbuser, allowedip, password respectively. The last 2 are optional. If the allowed IP is not specified the default subnet for that host is used. If the password is not specified a password is automatically generated.
The recipe format is designed to ease transition. The Flockport autopilot module provides far more advanced capabilities for both building and deploying containers.
You can see more recipes in the flockport/build folder or online at the Flockport repository.
The build command can also consume a github url. It will automaticaly download the repo and process any .recipe file to build the container.
flockport build https://www.github.com/flockport/redmine
Here is the actual recipe used to build Minio. The application is run as user minio.
NAME minio-201710
FROM alpine36
ENV MINIO_VERSION RELEASE.2017-10-27T18-59-02Z
ENV MC_VERSION RELEASE.2017-10-14T00-51-16Z
ENV MINIO_PATH /home/minio
RUN set -ex && \
addgroup -g 1100 minio && \
adduser -D -u 1100 -G minio minio
RUN mkdir -p $MINIO_PATH/bin /var/export
RUN curl -sSL https://dl.minio.io/server/minio/release/linux-amd64/minio.$MINIO_VERSION -o minio.$MINIO_VERSION && \
curl -sSL https://dl.minio.io/server/minio/release/linux-amd64/minio.$MINIO_VERSION.sha256sum -o minio.sha && \
sha256sum -c minio.sha && \
mv minio.$MINIO_VERSION $MINIO_PATH/bin/minio && \
chmod +x $MINIO_PATH/bin/minio
RUN curl -sSL https://dl.minio.io/client/mc/release/linux-amd64/mc.$MC_VERSION -o mc.$MC_VERSION && \
curl -sSL https://dl.minio.io/client/mc/release/linux-amd64/mc.$MC_VERSION.sha256sum -o mc.sha && \
sha256sum -c mc.sha && \
mv mc.$MC_VERSION $MINIO_PATH/bin/mc && \
chmod +x $MINIO_PATH/bin/mc
RUN ln -s $MINIO_PATH/bin/minio /usr/local/bin && \
ln -s $MINIO_PATH/bin/mc /usr/local/bin
RUN chown -R minio:minio $MINIO_PATH /var/export
COPY minio.openrc /etc/init.d/minio
RUN chmod +x /etc/init.d/minio && \
rc-update add minio default
You will notice we did not specify any ports or volumes in this recipe. These can also be specified when running the container as required.
The /var/export folder in the recipe is used as the minio data store. Currently it's in the container and data can be stored in the container without issue. Separation is not enforced in Flockport.
You can also use a host volume or a data volume container and attach it to the minio container. To specify it in the recipe we could add a volume entry.
VOLUME /var/export
This will share host folder /var/export with the container. We could also specify a data volume container.
VOLUME minio-data
Here minio-data is a pre-created data volume container with /var/export defined as the shared folder.
To use a data volume container you must create it first with the createvol command.
Minio uses the 9000 port and this can be forwarded at run time or specified in the recipe.
PORT 9000
This will forward port 9000 to the host on container start. Multiple ports can be specified.
PORT 80 3000 9000
This will forward container ports 80, 3000, and 9000 to the host.
You can also specify mappings to host ports if required with colons.
PORT 80:8080 3000:3100 9000:9100
This will forward PORT 80, 3000, and 9000 in the container to port 8080, 3100 and 9100 on the host respectively.
Remember you do not need to specify volumes or ports in the container. They can be specified at runtime.
For instance when you run this container you can use the command.
flockport run minio-201710 -v /var/export -p 80
This will attach the host /var/export to the container and forward container port 80.
One more important component of container build is the DB keyword.
Minio does not need a DB but most apps do. So how do you use a database in a recipe.
You can specify a DB with the DB keyword and the build systems will build the specified database container
DB mariadb10 wordpress wordpress
Another option is to use the FROM command to build from a database container. In this case you will have a single container with database integrated.
FROM mariadb10
This will use the mariadb10 container as the base container to build from.
Its generally a good idea to keep databases separate from the app container so app upgrades are simpler.
This is also used to build apps that are PHP based for instance and when building a wordpress container a php container is used as the base container.
NAME wordpress483
FROM php71
This uses the php71 container as the base container for the build.
For recipes that are single files and don't require any assets you can simply point to them.
flockport build nginx.recipe
flockport build /var/builds/nginx.recipe
This will build the container based on the nginx.recipe file.
You can also provide a github repo url to the build command.
flockport build https://github.com/flockport/recipes/nodejs
This will clone and repo and build the container based on the .recipe file found in the repo.
This is useful to have version control on your recipe repositories and directy build updated container as required.
It's also a quick and useful way to share your containers.
You can tag and group containers for easier management.
flockport tag c1 app db
Now c1 is tagged with app and db. Tags allow you to group containers and actions
You can use the info command to get a list of tags associated with a container
To perform groups actions simply use the -g flag
flockport -g db info
This will show you info on all containers with the db tag
flockport -g db start
This will start all container in the db group
You can also group containers.
flockport addgroup db
This creates a db group
Now you can add mutliple containers to the db group
flockport addgroup db c1 c2 c3
This adds containers c1 c2 c3 to the groub 'db'.
A group allows you to add multiple containers to a group. A tag allows you to add multiple tags to a container. All tags and groups are the same. The difference is in how you apply them
For instance to enable autostart on you can add the autostart tag
flockport tag c1 autostart
This will place c1 in the autostart group and enable container autostart on system boot. Similarly
flockport addgroup autostart c1 c2 c3
This will place c1, c2 and c3 in the autostart group and enable autostart on boot
You can use the deltag command to delete tags
flockport deltag c1 autostart
This deletes the autostart tag from c1 container
You can also use the delgroup command
flockport delgroup autostart c1
This deletes container c1 from the autostart group
To set cpu and memory limits on containers use the addlimit and dellimit commands
flockport addlimit c1 -c 1 -m 512M
This limits container c1 to 1 cpu and 512MB RAM
You can use the addlimit command to allocate CPU cores and memory. You can see the limits in action when you run htop inside the container.
You can remove limits with the dellimit command
flockport dellimit c1 -c -m
This resets any cpu and moeory limits set
Please note if there is only one cpu on your host then a container with a limit set will not start
On local systems all containers can access each other on the .app domain. So if you have an Nginx container for instance it can access a wordpress backend container at wordpress.app. This is configured into the dnsmasq instance that provides DHCP services to containers.