# How to Deploy Custom Chains with Custom Docker Images in Starship

> Deploy custom chains with custom Docker images in Starship. Follow our guide to create Dockerfiles, register versions, configure Helm, and test your deployment for seamless integration.

- Repository: [Hyperweb/starship](https://github.com/hyperweb-io/starship)
- Tags: how-to-guide
- Published: 2026-03-03

---

**To deploy a custom chain with a custom Docker image in Starship, create a Dockerfile in `starship/docker/chains/`, register it in [`versions.yaml`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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.

```dockerfile

# 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`](https://github.com/hyperweb-io/starship/blob/main/starship/docker/chains/versions.yaml) to add an entry pointing to your Dockerfile using the `file` field. This registration triggers the automated build pipeline.

```yaml
- 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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/starship/charts/defaults.yaml)** under the `defaultChains` section. This file defines the image reference, home directory, binary name, and tokenomics for the Starship CLI.

```yaml
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`](https://github.com/hyperweb-io/starship/blob/main/defaults.yaml) to override default initialization behavior.

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

```

Example script at [`starship/charts/scripts/mychain/create-genesis.sh`](https://github.com/hyperweb-io/starship/blob/main/starship/charts/scripts/mychain/create-genesis.sh):

```bash
#!/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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.

```yaml
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.

```bash
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`](https://github.com/hyperweb-io/starship/blob/main/starship/docker/chains/versions.yaml) using the `file` field to trigger automated builds via [`build-docker-chains.sh`](https://github.com/hyperweb-io/starship/blob/main/build-docker-chains.sh).
- **Configure Helm defaults** in [`starship/charts/defaults.yaml`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/starship/docker/chains/versions.yaml). When this field points to a Dockerfile path, the [`build-docker-chains.sh`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/starship/charts/defaults.yaml) without adding a Dockerfile to the repository. However, you must still add the chain name to [`values.schema.json`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/defaults.yaml) under the `scripts` key, such as `scripts.createGenesis.file`, to override the default initialization behavior provided by Starship.