Note: This article assumes that the application to be deployed into ToolForge already exists in container format. For more information about how to build an application for ToolForge, check out the GitHub template repositories for Java and Python.

Creating the Container Repository

Before the application container can be pushed into the ToolForge container repository, the repository must be created.

The new Container may be created in the UI or API. The new Container's name and description will appear in its container listing in the marketplace, so choose carefully. The name must be unique among all containers owned by the user or organization. Both the name and description can be changed later.

Pushing to the Container Repository

Now that the container repository has been created, the container can be pushed into the ToolForge container registry, docker.toolforge.io.

First, you'll need to generate a set of credentials for logging into the registry:

curl -XPOST  
    -H "authorization: bearer $TOOLFORGE_API_KEY"  
    https://api.toolforge.io/v1/docker/otp

In the above command, you'd need to replace $TOOLFORGE_API_KEY with a valid API key. If you don't have an API key, you can learn how to create one here.

The above command will return a one-time password (OTP) you can use to log into the docker registry:

docker login -u $USERNAME docker.toolforge.io

In the above command, you'd need to replace $USERNAME with your ToolForge username, and paste the OTP to complete the login.

By default, the session lasts for 8 hours. During that time, you can push your image to the container repository:

docker build -t docker.toolforge.io/$USERNAME/$SLUG

docker push docker.toolforge.io/$USERNAME/$SLUG

Of course, you can build your container another way, but it must be tagged using the ToolForge repository name. It can then be pushed. The container's exact repository name may be found in the UI or API, if needed.

Verifying the Container Push

In order to be a valid ToolForge tool, a container must meet several criteria:

• Linux-based
• ARM64 or AMD64 architecture
• A valid ToolForge manifest at /toolforge/manifest.yml

Each complete, successful container push will result in log entries in the Container's logs. The log entries will indicate whether the push contained a valid container, and if not, what issue(s) were found that need correction. The logs may be checked in the UI or API.

If the container was valid, then a new version of the Container is created.

Releasing the New Container Version

The new version should exist in the ready state, which indicates that it has been accepted as a valid tool image and can be released. This new version can be released using the UI or API. This will change the state of the new version from ready to current and change the state of the old versions to deprecated.

Updating Tool Installs

Once the new Container version has been released, all new installations of the Container as a Tool will use the new (now current) version. All existing tool installations will continue to use their existing container version until they are updated. Users will be notified that an update is available every time they create an execution from a Tool using a deprecated version of a Container.