How to Deploy Custom Chains with Custom Docker Images in Starship

To deploy a custom chain with a custom Docker image in Starship, create a Dockerfile in starship/docker/chains/, register it in versions.yaml, configure the Helm defaults, and validate with an end-to-end test.

Starship is an interchain development environment that orchestrates blockchain nodes in Kubernetes. When you need to deploy a custom chain that is not natively supported, you must build a bespoke Docker image and wire it into the Starship Helm charts. This guide walks through the complete workflow based on the hyperweb-io/starship source code and the official docs/development/add-new-chain.md walkthrough.

Overview of the Custom Chain Deployment Workflow

Starship runs each blockchain node in its own Docker container. To add support for a new chain with a custom image, you must complete four phases: image creation, registry configuration, Helm chart integration, and automated testing. Each phase touches specific files in the repository that govern how the CLI generates Kubernetes manifests.

Building the Custom Docker Image

Creating the Dockerfile

Place your custom Dockerfile under starship/docker/chains/. The image must include the chain binary plus Starship utilities (bash, curl, make, jq, sed). These dependencies are required for initialization scripts that handle genesis creation and health checks.

# starship/docker/chains/Dockerfile.mychain

FROM golang:1.21-bullseye AS builder
WORKDIR /src
RUN git clone https://github.com/yourorg/mychain.git .
RUN make build

FROM debian:bullseye-slim
RUN apt-get update && apt-get install -y curl jq bash sed && rm -rf /var/lib/apt/lists/*
COPY --from=builder /src/build/mychaind /usr/local/bin/
ENTRYPOINT ["mychaind"]

Registering the Image in versions.yaml

Edit starship/docker/chains/versions.yaml to add an entry pointing to your Dockerfile using the file field. This registration triggers the automated build pipeline.

- name: mychain
  base: golang:1.21-bullseye
  file: starship/docker/chains/Dockerfile.mychain
  tags:
    - v1.0.0

Building and Publishing

The starship/docker/chains/build-docker-chains.sh script automatically builds any entry containing a file key. It constructs the image and publishes it to the GitHub Container Registry (GHCR) as ghcr.io/cosmology-tech/starship/mychain:v1.0.0. Run this script locally or via CI to push your image.

Configuring the Helm Chart for Your Chain

Updating defaults.yaml

Add your chain specification to starship/charts/defaults.yaml under the defaultChains section. This file defines the image reference, home directory, binary name, and tokenomics for the Starship CLI.

mychain:
  image: ghcr.io/cosmology-tech/starship/mychain:v1.0.0
  home: /root/.mychain
  binary: mychaind
  prefix: my
  denom: umycoin
  prettyName: MyChain
  coins: 100000000000000umycoin
  hdPath: m/44'/118'/0'/0/0
  coinType: 118
  repo: https://github.com/yourorg/mychain

Adding Custom Genesis and Validator Scripts

If your chain requires specialized genesis handling, create shell scripts under starship/charts/scripts/<chain-name>/. Reference these files in defaults.yaml to override default initialization behavior.

scripts:
  createGenesis:
    file: scripts/mychain/create-genesis.sh

Example script at starship/charts/scripts/mychain/create-genesis.sh:

#!/usr/bin/env bash
set -euo pipefail

mychaind init mynode --chain-id mychain-1
mychaind add-genesis-account $(mychaind keys show validator -a) 1000000000000umycoin
mychaind gentx add-genesis-validator $(mychaind keys show validator -a) --amount=1000000umycoin --pubkey=$(mychaind tendermint show-validator)
mychaind collect-gentxs

Enabling Schema Validation

Register the chain name in starship/charts/devnet/values.schema.json under .properties.chains.items.properties.name.enum. This step enables the Starship CLI to validate the chain name in user configuration files before deploying to Kubernetes.

Validating with End-to-End Tests

Creating the Test Configuration

Create a test file under starship/tests/e2e/configs/mychain.yaml. This configuration spins up a minimal devnet to verify your custom image integrates correctly with Starship’s orchestration layer.

chains:
  - name: mychain
    image: ghcr.io/cosmology-tech/starship/mychain:v1.0.0
    validatorCount: 1
    ports:
      rpc: 26657
      rest: 1317
      faucet: 8000

Running the Test Locally

Execute the test suite from the starship/tests/e2e directory to deploy the chain, forward ports, and run integration checks.

cd starship/tests/e2e
make install HELM_FILE=configs/mychain.yaml
make port-forward HELM_FILE=configs/mychain.yaml
make test HELM_FILE=configs/mychain.yaml

This pipeline verifies that your custom Docker image boots correctly, accepts connections on the specified ports, and passes all health checks within the Starship environment.

Summary

• Create a Dockerfile in starship/docker/chains/ that bundles your chain binary with required utilities (bash, curl, jq, sed, make).
• Register the build in starship/docker/chains/versions.yaml using the file field to trigger automated builds via build-docker-chains.sh.
• Configure Helm defaults in starship/charts/defaults.yaml with image references, binary paths, and chain parameters.
• Add custom scripts under starship/charts/scripts/<chain-name>/ for specialized genesis or validator setup logic.
• Update the JSON schema in starship/charts/devnet/values.schema.json to enable CLI validation of your chain name.
• Write an e2e test in starship/tests/e2e/configs/ to verify the complete deployment pipeline before submitting your PR.

Frequently Asked Questions

What utilities must be included in a custom Starship Docker image?

The base image must contain bash, curl, make, jq, and sed. These utilities are required by the Starship initialization scripts that handle genesis creation, validator setup, and health checks inside the container runtime.

How does Starship know which Docker image to build for my custom chain?

Starship reads the file field in starship/docker/chains/versions.yaml. When this field points to a Dockerfile path, the build-docker-chains.sh script automatically builds the image and publishes it to GHCR with the specified tags, making it available for Helm deployments.

Can I use an existing public Docker image instead of building one?

Yes. If your chain binary is already available in a public registry, you can reference it directly in starship/charts/defaults.yaml without adding a Dockerfile to the repository. However, you must still add the chain name to values.schema.json and define the configuration defaults for the Starship CLI to recognize it.

Where do I place custom initialization logic for my chain?

Place custom genesis or validator scripts under starship/charts/scripts/<chain-name>/. Reference these files in defaults.yaml under the scripts key, such as scripts.createGenesis.file, to override the default initialization behavior provided by Starship.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}