Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion docs/dev/package-development/multi-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,14 @@ package_variants/

The contents within each variant directory include the fields that differ from one variant to another. When building a specific variant, such as `testnet`, the data from these variant-specific files is merged with the root-level `dappnode_package.json` and `docker-compose.yml`. This ensures that only the necessary variant-specific changes are applied, while the common configuration remains consistent across all variants.

### Manifest identity and inheritance

The root manifest holds shared fields and omits `name` and `version`. Each variant supplies its own package ENS name and registry version; the merged manifest is validated as the installable package.

Manifest objects merge recursively, scalars are overridden, and arrays merge by index. Shorter variant arrays inherit the root’s trailing entries; an empty array does not clear a root array. For `upstream[]`, retain the same repository at each overlapping position. Do not reorder entries to select a different upstream.

After merging, every `upstream[].arg` must exist in the compose and every service declaring it must match the upstream version. Explicit `mainService`, `chain.serviceName`, `backup[].service` and `globalEnvs[].services` values must name services in the resolved compose.

You can add more variants as needed by creating additional directories and files following this structure.

### Customize the Avatar
Expand All @@ -76,7 +84,7 @@ Example of a variant-specific `dappnode_package.json`:

And the corresponding `docker-compose.yml`:

```json
```yaml
version: "3.5"
services:
test:
Expand Down
14 changes: 14 additions & 0 deletions docs/dev/package-development/single-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,20 @@ In the `dappnode_package.json`, update fields such as:
- `name`, `version`, `description`, and `author` to reflect your package.
- Add relevant `categories`, `architectures`, and exposed services (e.g., API endpoints).

### Declare upstream software

Use `upstream[]` to connect each upstream repository to an explicit compose build argument. The upstream version is separate from the package’s own `version`.

```json
{
"upstream": [
{ "repo": "ethereum/go-ethereum", "version": "v1.2.3", "arg": "UPSTREAM_VERSION" }
]
}
```

Set `build.args.UPSTREAM_VERSION` to `v1.2.3` in every compose service that declares it. See the [manifest reference](../references/manifest.md#upstream) for the full contract.

### Simplified Dockerfile

Here’s a simplified version of the Dockerfile inside the `geth` directory:
Expand Down
41 changes: 25 additions & 16 deletions docs/dev/references/docker-compose.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,28 +79,37 @@ In the complex example, you'll find:
- All environment variables (`envs`) defined in the `docker-compose.yml` file will be visible in the package config post-installation. Users can modify these.
- If the package has a `setup-wizard`, those environment variables not set within it will be hidden by default in the configuration. Users can view these by selecting "Show advanced config".

#### The `UPSTREAM_VERSION` Argument
#### Upstream build arguments

- The `UPSTREAM_VERSION` argument is mandatory if you wish to leverage GitHub actions that automatically create PRs when there's a new release in the upstream repository.
- In the Dockerfile, `UPSTREAM_VERSION` is usually declared and used like this:
Declare an explicit argument for each upstream, such as `UPSTREAM_VERSION`, `GETH_VERSION` or `TEKU_VERSION`. The name is not fixed; it must match `upstream[].arg` exactly. Use a mapping under `build.args`.

```dockerfile
ARG UPSTREAM_VERSION
FROM consensys/teku:$UPSTREAM_VERSION
```
Manifest excerpt:

:::note
The `upstreamVersion` and `upstreamRepo` fields need to be defined in the `dappnode_package.json` file for the GitHub actions to work. Here is an example:

```
```json
{
...
"upstreamVersion": "23.8.0",
"upstreamRepo": "ConsenSys/teku",
...
"upstream": [
{ "repo": "ConsenSys/teku", "version": "v4.0.7", "arg": "TEKU_VERSION" }
]
}
```
:::

Corresponding compose build configuration:

```yaml
services:
beacon-chain:
build:
context: beacon-chain
args:
TEKU_VERSION: v4.0.7
```

```dockerfile
ARG TEKU_VERSION
FROM consensys/teku:${TEKU_VERSION}
```

If several services declare `TEKU_VERSION`, every value must match the manifest version. A digest pin must contain the same version followed by `@sha256:` and 64 hexadecimal characters. The legacy top-level `upstreamRepo`, `upstreamVersion` and `upstreamArg` fields are deprecated; use the [upstream array](manifest.md#upstream).

#### The `EXTRA_OPTS` Environment Variable

Expand Down
Loading
Loading