Update docker

building/config.json

@@ -717,6 +717,13 @@
     "title": "Tooling Docker Setup",
     "blurb": ""
   },
+  {
+    "uuid": "83dc65b9-cc74-4a2a-9c70-472f6416c19d",
+    "slug": "tooling/best-practices",
+    "path": "building/tooling/best-practices.md",
+    "title": "Best Practices",
+    "blurb": ""
+  },
   {
     "uuid": "b080e814-d3b9-4027-a25e-907f5505cf8d",
     "slug": "tooling/analyzers",

building/tooling/analyzers/README.md

@@ -21,3 +21,4 @@ You can use the following documents to learn more about building an analyzer:
 - [Writing Analyzer comments](/docs/building/tooling/analyzers/comments)
 - [Tagging solutions](/docs/building/tooling/analyzers/tags)
 - [Guidance for building an Analyzer](/docs/building/tooling/analyzers/guidance)
+- [Best practices](/docs/building/tooling/best-practices)

building/tooling/best-practices.md

@@ -0,0 +1,90 @@
+# Best Practices
+
+## Follow best practices
+
+The official [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) have lots of great content on how to improve your Dockerfiles.
+
+## Prefer official images
+
+There are many Docker images on [Docker Hub](https://hub.docker.com/), but try to use [official ones](https://hub.docker.com/search?q=&image_filter=official).
+
+## Pin versions
+
+To ensure that builds are stable (i.e. they don't suddenly break), you should always pin your base images to specific tags.
+That means instead of:
+
+```dockerfile
+FROM alpine:latest
+```
+
+you should use:
+
+```dockerfile
+FROM alpine:3.20.2
+```
+
+With the latter, builds will always use the same version.
+
+## Performance
+
+You should primarily optimize for performance (especially for test runners).
+This will ensure your tooling runs as fast as possible and does not time-out.
+
+### Experiment with different Base images
+
+Try experimenting with different base images (e.g. Ubuntu instead of Alpine), to see if one (significantly) outperforms the other.
+If performance is relatively equal,
+
+### Try Internal Network
+
+Check if using the `internal` network instead of `none` improves performance.
+See the [network docs](/docs/building/tooling/docker#network) for more information.
+
+### Prefer build-time commands over run-time commands
+
+Tooling runs as one-off, short-lived Docker container:
+
+1. A Docker container is created
+2. The Docker container is run with the correct arguments
+3. The Docker container is destroyed
+
+Therefore, code that runs in step 2 runs for _every single tooling run_.
+For this reason, reducing the amount of code to run in step 2 is a great way to improve performance
+One way of doing this is to move code from _run-time_ to _build-time_.
+Whilst run-time code runs every single tooling run, build_time code only runs once (when the Docker image is built).
+
+As build-time code runs as part of a GitHub Actions workflow, the student will never notice it.
+This also means that the code at build-time could be relatively slow, it's only running once after all!
+
+## Size
+
+You should try to reduce the image's size, which means that it'll be:
+
+- Faster to deploy
+- Reduces costs for us
+- Marginally improves startup time of each container
+
+### Try different Base images
+
+Some base images are
+
+### Removing unneeded bits
+
+An obvious, but great, way to reduce the size of your image is to remove anything you don't need.
+These can include things like:
+
+- Source files that are no longer needed after building a binary from them
+- Files targeting different architectures from the Docker image
+- Documentation
+
+### Cleanup package manager
+
+### Use multi-stage builds
+
+https://docs.docker.com/build/building/multi-stage/
+
+TODO
+
+## Safety
+
+TODO

building/tooling/docker.md

@@ -1,14 +1,12 @@
-# Tooling Docker Setup
+# Docker Setup
 
 Our various track tooling are deployed as Docker images.
 
-Each piece of tooling requires a Dockerfile, which specifies how the machine is built.
+Each piece of tooling requires a [Dockerfile](https://docs.docker.com/reference/dockerfile/), which specifies how the machine is built.
 It should live at the root directory of your repository and should be called `Dockerfile`.
 
 The Dockerfile should create the minimal image needed for the tooling to function correctly and speedily.
-
-The Dockerfile should produce an image with as a small a size as possible while maximizing (and prioritizing) performance.
-Applying the official [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) can help to create a minimal image.
+Our [Best Practices page](/docs/building/tooling/best-practices) has lots of tips to help you achieve this goal.
 
 ## Execution
 
@@ -20,15 +18,15 @@ At the end of that period it will be timed out with a 408 error code.
 ### Stdout/stderr
 
 A tooling run may produce up to a maximum of one-megabyte of stdout and stderr.
-If it produces more it will be killed with a 413 error code.
+If it produces more, it will be killed with a 413 error code.
 
 The contents of `stdout` and `stderr` from each run will be stored in files that can be viewed later.
 
-You may write an `results.out` file to the output directory, which contains debugging information you want to later view.
+You may write a `results.out` file to the output directory, which contains debugging information you want to view later.
 
 ### Results
 
-The results file may be no larger than 500 kilobytes (including any stack traces etc).
+The results file may not be larger than 500 kilobytes (including any stack traces etc).
 If the file is larger than this, the tooling run will be killed with a 460 error code.
 
 ## Configuration
@@ -37,7 +35,8 @@ Each solution gets 100% machine resources for a twenty second window.
 
 After 20 seconds, the process is halted and reports as a time-out.
 
-Configuration can be set in the [`tools.json` file](https://github.com/exercism/tooling-invoker/blob/main/tools.json) in the Tooling Invoker repository.
+Some tools require (slight) deviations from the default configuration.
+If so, these are configured in the [`tools.json` file](https://github.com/exercism/tooling-invoker/blob/main/tools.json) in the Tooling Invoker repository.
 
 ### Network
 
@@ -51,6 +50,21 @@ Different languages perform better/worse with different configurations (e.g. Rub
 You can experiment locally by using the `--network` flag when running your docker. `--network none` is supported by default.
 To use the internal network, first run `docker network create --internal internal` to create the network, then use `--network internal` when running the container.
 
+### Read-only filesystem
+
+We encourage Docker files to be written using a read-only filesystem.
+The only directories you should assume to be writeable are:
+
+- The solution dir (passed in as the second argument)
+- The output dir (passed in as the third argument)
+- The `/tmp` dir
+
+```exercism/caution
+Our production environment currently does _not_ enforce a read-only filesystem, but we might in the future.
+For this reason, the base template for a new test runner/analyzer/representer starts out with a read-only filesystem.
+If you can't get things working on a read-only file, feel free to (for now) assume a writeable file system.
+```
+
 ### Memory
 
 Languages can set the maximum memory they need to use to run their jobs. Setting this to be as low as possible means that we can run more jobs more quickly in parallel. It also means that people who try and abuse memory will not be able to succeed. Different languages need wildly different maximum memory usage. Benchmarking the execution of a docker run to establish the maximum memory it uses is advised and appreciated.
@@ -67,4 +81,4 @@ docker container run -v /path/to/job:/mnt/exercism-iteration --network none -m 1
 
 ## Editing a Dockerfile
 
-All changes to Dockerfiles require a PR review from the @exercism/ops team, in order to avoid the introduction of security exploits.
+All changes to Dockerfiles require a PR review from the `@exercism/maintainers-admin` team, in order to avoid the introduction of security exploits.

building/tooling/representers/README.md

@@ -35,3 +35,4 @@ You can use the following documents to learn more about building a representer:
 - [The Representer interface](/docs/building/tooling/representers/interface)
 - [How to normalize representations for the highest efficiency](/docs/building/tooling/representers/normalization)
 - [How to build a Docker image with Docker for local testing and deployment](/docs/building/tooling/representers/docker)
+- [Best practices](/docs/building/tooling/best-practices)

building/tooling/test-runners/README.md

@@ -23,3 +23,4 @@ You can use the following documents to learn more about building a test runner:
 - [creating a Test Runner from scratch](/docs/building/tooling/test-runners/creating-from-scratch)
 - [The Test Runner interface](/docs/building/tooling/test-runners/interface)
 - [How to build a Docker image with Docker for local testing and deployment](/docs/building/tooling/test-runners/docker)
+- [Best practices](/docs/building/tooling/best-practices)