> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canton.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Darsyncer Docker Image

> Upload and synchronize DAR files to a participant.

# darsyncer

`darsyncer` synchronizes one or more DAR files to a participant ledger. It can upload missing DARs, verify that required packages are present, or wait until synchronization has completed.

## Docker Image

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest
```

## Features

* Upload one or more DAR files to a participant
* Synchronize an entire directory of DARs
* Verify that required DARs are already available
* Wait until a participant has received all required DARs
* OAuth authentication support
* Configurable transport security
* Health probe endpoint for Kubernetes deployments

## Pulling the Image

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker pull europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest
```

### Available Versions

Released versions of darsyncer are browsable through the Google Artifact Registry UI (accessible to all, but does require you to log in to Google).

| Source          | Location                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Browse UI       | <a href="https://console.cloud.google.com/artifacts/docker/da-images/europe/public/docker%2Fdarsyncer?project=da-images">Browse available image versions</a> |
| Docker Registry | `europe-docker.pkg.dev/da-images/public/docker/darsyncer:<version-tag>`                                                                                      |

If you do not specify a tag, Docker defaults to pulling `:latest`. This documentation uses `:latest` as an example; if you need a pinned version, use an immutable image digest (for example, `europe-docker.pkg.dev/da-images/public/docker/darsyncer@sha256:<digest>`) rather than a floating tag.

Generally speaking, darsyncer versions are compatible across participant/Splice versions, and it is advantageous to stay current to benefit from security vulnerability fixes and other patches.

## Quick Start

Assuming your DAR files are located in `./dars`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  -v $(pwd)/dars:/dars:ro \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --endpoint participant.example.com:443 \
  --dars /dars
```

## Usage

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
darsyncer [global options]
```

### Required Options

| Option       | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `--endpoint` | Participant endpoint to synchronize to.                        |
| `--dars`     | Path to a single DAR file or a directory containing DAR files. |

## Command-Line Options

### General

| Option                 | Description                                                                 | Default                         |
| ---------------------- | --------------------------------------------------------------------------- | ------------------------------- |
| `--dars`               | Path to a DAR file or directory.                                            |                                 |
| `--log`                | Log level.                                                                  | `info`                          |
| `--transport-security` | Connection security mode (`https-with-plaintext-fallback` or `https-only`). | `https-with-plaintext-fallback` |
| `--help`               | Show help information.                                                      |                                 |

### Authentication

These options may also be provided using environment variables.

| Option            | Environment Variable | Description               |
| ----------------- | -------------------- | ------------------------- |
| `--audience`      | `AUDIENCE`           | OAuth audience            |
| `--client-id`     | `CLIENT_ID`          | OAuth client ID           |
| `--client-secret` | `CLIENT_SECRET`      | OAuth client secret       |
| `--oauth-domain`  | `OAUTH_DOMAIN`       | OAuth domain              |
| `--scope`         | `SCOPE`              | OAuth scope               |
| `--token-path`    | `TOKEN_PATH`         | Path to a JWKS token file |

### Modes

| Option             | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `--endpoint`       | Participant endpoint                                        |
| `--check`          | Verify the participant already contains all DARs and exit   |
| `--wait`           | Wait until the participant contains all DARs before exiting |
| `--just-print`     | Print package IDs without uploading                         |
| `--probe-endpoint` | Health probe bind address                                   |
| `--retry-delay`    | Delay between retry attempts                                |

## Examples

### Upload all DARs from a directory

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  -v $(pwd)/dars:/dars:ro \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --endpoint participant.example.com:443 \
  --dars /dars
```

### Upload a single DAR

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  -v $(pwd)/dars:/dars:ro \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --endpoint participant.example.com:443 \
  --dars /dars/example.dar
```

### Verify required DARs

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  -v $(pwd)/dars:/dars:ro \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --endpoint participant.example.com:443 \
  --dars /dars \
  --check
```

### Wait until synchronization completes

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  -v $(pwd)/dars:/dars:ro \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --endpoint participant.example.com:443 \
  --dars /dars \
  --wait
```

### Print package IDs

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  -v $(pwd)/dars:/dars:ro \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --dars /dars \
  --just-print
```

## Using Environment Variables

Authentication parameters can be supplied through environment variables.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  -v $(pwd)/dars:/dars:ro \
  -e CLIENT_ID=my-client \
  -e CLIENT_SECRET=my-secret \
  -e AUDIENCE=my-audience \
  -e OAUTH_DOMAIN=https://auth.example.com \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --endpoint participant.example.com:443 \
  --dars /dars
```

## Health Probe

By default, the health probe server listens on:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
0.0.0.0:8080
```

To change the address:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
--probe-endpoint 0.0.0.0:9090
```

This endpoint is intended for Kubernetes liveness and readiness probes.

## Logging

Configure the log level:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
--log info
```

Default:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
info
```

## Transport Security

| Mode                            | Description                                                 |
| ------------------------------- | ----------------------------------------------------------- |
| `https-with-plaintext-fallback` | Attempt HTTPS first and fall back to plaintext if necessary |
| `https-only`                    | Require HTTPS for all participant connections               |

## Volume Mounts

Mount a directory containing DAR files into the container.

Example:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
-v $(pwd)/dars:/dars:ro
```

## Environment Variables

| Variable        | Description           |
| --------------- | --------------------- |
| `DARS`          | DAR file or directory |
| `ENDPOINT`      | Participant endpoint  |
| `CLIENT_ID`     | OAuth client ID       |
| `CLIENT_SECRET` | OAuth client secret   |
| `AUDIENCE`      | OAuth audience        |
| `OAUTH_DOMAIN`  | OAuth provider        |
| `SCOPE`         | OAuth scope           |
| `TOKEN_PATH`    | JWKS token file       |

## Troubleshooting

### No DARs Found

Verify that:

* the mounted directory contains `.dar` files;
* the path supplied to `--dars` is correct; and
* the directory is mounted into the container.

### Authentication Failures

Confirm that:

* the OAuth credentials are valid;
* the configured audience and scope are correct; and
* the participant accepts the supplied credentials.

### Unable to Connect

Verify:

* the participant endpoint is reachable;
* the selected transport security mode matches the participant configuration; and
* network policies or firewalls allow the connection.

## Display Help

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  europe-docker.pkg.dev/da-images/public/docker/darsyncer:latest \
  --help
```

## Contribution

darsyncer is an open sourced component available at [https://github.com/digital-asset/darsyncer](https://github.com/digital-asset/darsyncer) - contributions and enhancements are welcome.