Skip to content

docs(install.adoc) Add podman guide #798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 26, 2021
Merged
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 55 additions & 7 deletions docs/modules/setup/pages/install.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
:uri-docker-get-started: https://docs.docker.com/get-started/
:uri-docker-compose-install: https://docs.docker.com/compose/install/
:uri-docker-container-networking: https://docs.docker.com/config/containers/container-networking/
:uri-podman-get-started: https://podman.io/getting-started/
:uri-podman-compose-install: https://github.com/containers/podman-compose
:uri-k8s-publish-service: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
:uri-k8s-definition-files: https://raw.githubusercontent.com/yuzutech/kroki/master/docs/modules/setup/examples/k8s

Expand All @@ -24,24 +26,25 @@ you first need to install the gateway server.

[TIP]
====
We recommend installing Kroki using *Docker*, especially if you don't want to manually install diagrams libraries.
We recommend installing Kroki using containers with either *Docker* or *Podman*, especially if you don't want to manually install diagrams libraries.

However, you can also install each diagrams libraries that you want to use and run the gateway server as a _standalone executable jar_.
Consult the xref:manual-install.adoc[manual install page] to find out how.
====

Assumptions:

* [x] {uri-docker-get-started}[Docker] is installed on your machine.
* [x] {uri-docker-compose-install}[Docker Compose] is installed on your machine (optional).

On this page, you'll learn:

* [x] How to run Kroki
* [x] How to configure Kroki

== Using Docker

Assumptions:

* [x] {uri-docker-get-started}[Docker] is installed on your machine.

To start the Kroki gateway server, run the command:

[source,docker-cli]
docker run yuzutech/kroki

Expand All @@ -64,7 +67,14 @@ docker run -p8080:8000 -d yuzutech/kroki
== Using docker-compose

You can use `docker-compose` to run multiple containers.
Here's an example where we start all the containers:

Assumptions:

* [x] {uri-podman-get-started}[Podman] is installed on your machine.
* [x] {uri-podman-compose-install}[Podman-compose] is installed on your machine.

Here's an example where we start all the containers.
In this example host port 8000 is exposed.

.docker-compose.yml
[source,yml]
Expand All @@ -75,6 +85,44 @@ include::example$kroki-docker-compose.yml[]
[source,docker-cli]
docker-compose up -d

== Using Podman

Podman is a drop-in replacement for Docker for Linux systems only, and is available for many distributions.
It is light-weight, does not need a daemon running in the background, and is built with container security in mind.

Using Podman is a useful learning, development and testing step for running pods of containers in your linux environment.
It is also a useful intermediate step if you are looking to lift your Kroki implementation into a Kubernetes environment.

Assumptions:

* [x] {uri-docker-get-started}[Docker] is installed on your machine.

To start the Kroki gateway server using `podman`, run the command:

[source,docker-cli]
podman run yuzutech/kroki

NOTE: The only difference is using `podman` instead of `docker`.


== Using podman-compose

To start a set of containers together in the same pod, use `podman-compose`.
It is a helper program for podman with the same purpose as `docker-compose` except that it runs containers without a daemon and in certain configurations is able to run as a normal user instead of root.

Using podman-compose does not require installing the docker-compose application.

NOTE: This is different to the latest release of Podman v3, which requires `docker-compose` be installed.

Assumptions:

* [x] {uri-podman-get-started}[Podman] is installed on your machine.
* [x] {uri-podman-compose-install}[Podman-compose] is installed on your machine.

To use the the same docker-compose.yml file as in <<using-docker-compose>> and bring up your pod, run the command:

[source,docker-cli]
podman-compose up -d

=== Images

Expand Down