This article describes the usage of the FirstSpirit Docker image. The image allows for starting FirstSpirit easily in an arbitrary version. It is designed primarily for developers who want to test their modules or develop FirstSpirit projects locally and should not be used in a productive environment. Apart from Docker, there are no requirements to the host system like an installed Java version.
The image setup adheres to the official installation instructions, thus providing a FirstSpirit server installed according to the best practice. It behaves like any other Docker image, for example it only starts FirstSpirit: a Tomcat web-server has to be attached with a second container.
System Requirements
On the host system a configured Docker installation is required that is ready to run containers. This varies depending on the operating system, instructions for Linux, MacOS and Windows are available.
You can test your Docker setup with the Hello World image:
$ docker run hello-world
Starting the Container
In the most simple case, start the image in the favoured version:
$ docker run --rm -p8000:8000 docker.artifactory.e-spirit.hosting/e-spirit/firstspirit:5.2.241009
If you receive an error that the image could not be found, you might need to authenticate first:
$ docker login docker.artifactory.e-spirit.hosting
After the server startup has completed, the start page can be found on http://localhost:8000 and a login using the default credentials is possible. A license is not installed, so the server will shutdown after 30 minutes automatically. In order to stop the server, press Ctrl+C on the terminal used to start the container.
Persisting Configuration and Data
If no volume has been defined, the image will use an anonymous volume for the FirstSpirit directory. It is possible to define a dedicated volume or a bind mount instead.
Creating a volume is done with the command
$ docker volume create firstspirit
Here "firstspirit" is an identifier that can be chosen freely. Afterwards the container is started with the volume:
$ docker run --rm -p8000:8000 \
-v firstspirit:/opt/firstspirit5 \
docker.artifactory.e-spirit.hosting/e-spirit/firstspirit:5.2.241009
If the persistence should be performed on the host system, the container may be started with a bind mount instead:
docker run --rm -p8000:8000 \
-v /home/user/data/fs:/opt/firstspirit5 \
docker.artifactory.e-spirit.hosting/e-spirit/firstspirit:5.2.241009
Frequently Asked Questions
How can I Configure a Debug Port for the FirstSpirit Server?
After persisting the configuration (see above) edit the file "conf/fs-wrapper-isolated.conf":
wrapper.java.additional.9=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
This opens the port 5005 inside the Docker image. In order to make it accessible on the host system, add the port to the run command:
docker run --rm -p8000:8000 -p5005:5005 [...]
The server should contain pre-installed modules. How can that be accomplished?
Installing a module using ServerManager may be a repetitive task slowing down the development cycle. In order to place the module in the FirstSpirit server automatically, there are two different ways:
- Before the server is started, place the FSM file in the "data/modules" directory
- After the server is started, use fs-cli to install the FSM:
$ fs-cli.sh module install --fsm dev.fsm
Please note that fs-cli requires a valid license installed for the FirstSpirit server.
How can I import a project programmatically?
Other than modules, FirstSpirit projects can only be installed once the server is up and running. The easiest way is using fs-cli:
$ fs-cli.sh project import --importProjectName Mithras --projectFile mithras-energy.tar.gz
