Table of Contents
Even if you follow the recommended development process and use our tfw.sh script, it can still be quite useful to understand the build process (i.e. in case you ever need to troubleshoot something). Let's see how to build/run a TFW based challenge manually.
The relationship between images
First of all, let's take a look at the FROM statements in our Dockerfiles:
# frontend-tutorial-framework:
FROM avatao/debian:buster
# baseimage-tutorial-framework (multistage build):
FROM avatao/frontend-tutorial-framework:chausie-20190915 as frontend
FROM avatao/debian:buster
############## Implementation details above this line ##############
# test-tutorial-framework (or your challenge):
FROM avatao/baseimage-tutorial-framework
The baseimage-tutorial-framework uses a multistage Docker build to include the necessary build artifacts of the frontend (static html and js files, which will be served by nginx).
Every baseimage release has a compatible frontend version bundled into it using this mechanism.
Your challenge should use the TFW baseimage (avatao/baseimage-tutorial-framework), which is available on Docker Hub.
Notice the tags in the image names (i.e. chausie-20190915).
The chausie part before the dash is the major version and the timestamp 20190915 is the minor version.
Updating challenges to new minor versions should be safe and easy, as we try our best not to introduce any breaking changes during the lifetime of a given major release.
A new major indicates that some public API has changed, and the upgrade procedure should be done manually with extra care.
Note that due to limited resources, we only support the latest major version at all times (i.e. no bugfixes and/or new features for older releases).
The latest major chausie was intended for long term support and should be the version we use in the foreseeable future (no further API breakages are planned for now).
The example Dockerfile in test-tutorial-framework does not specify a tag (therefore it defaults to latest).
You should edit this file and pin the latest TFW tag in your Dockerfile to keep your builds nice & reproducible.
It should look similar to this:
# test-tutorial-framework (or your challenge):
FROM avatao/baseimage-tutorial-framework:chausie-20190915
You can find available releases here. Generally speaking you should always try to use the newest one for the best experience.
Building your challenge
It is practical to bootstrap the creation of your challenge from the test-tutorial-framework repository, which serves as a nice template project. Clone this repository and enter these commands to build it:
cd test-tutorial-framework
docker build -t test-tutorial-framework -f solvable/Dockerfile .
Finally, you can run the container using this command:
docker run --rm -p 8888:8888 -e AVATAO_SECRET=secret test-tutorial-framework
By default TFW exercises only expose port 8888 for HTTP and use a reverse proxy inside the container to allow running multiple services.
The AVATAO_SECRET envvar is used by a custom PAM module in the avatao/debian:buster image to inject secrets at runtime for authentication (for challenges with SSH for instance).