Deployment Basics

This guide explains how to deploy Asset Core write and read daemons on a single node with durable storage. It is the baseline you should validate before moving to more complex topologies.

Prerequisites

Make sure you can run both daemons with persistent storage and that you have permissions to write to the target directories. In production, these directories should be backed up and monitored.

• Built Asset Core binaries (cargo build --release)
• Writable directory for commit log, checkpoints, and auth tokens
• Ports 8080 and 8081 available (or alternatives)

Step 1 - Prepare directories

Create directories for persistent state:

mkdir -p /var/lib/assetcore/{data,logs,auth/tokens}

The commit log, checkpoints, and token files will be stored here. Treat this directory as operationally critical.

Step 2 - Configure the write daemon

Create a configuration file write.toml:

[paths]
base_dir = "/var/lib/assetcore"

[server]
host = "0.0.0.0"
port = 8080

[commit_log]
path = "data/commit_log.log"

[commit_log_driver]
checkpoint_path = "data/write.checkpoint.json"

[namespaces]
catalog_backend = "sqlite"
catalog_path = "data/namespace_catalog.sqlite"

[auth]
directory = "auth/tokens"

Key settings:

Setting	Description
server.host/server.port	Address and port to bind
commit_log.path	Where to store the event log
commit_log_driver.checkpoint_path	Write daemon checkpoint
auth.directory	Bearer token directory
namespaces.catalog_path	Namespace catalog SQLite file

Step 3 - Configure the read daemon

Create a configuration file read.toml or use command-line arguments:

[paths]
base_dir = "/var/lib/assetcore"

[server]
address = "0.0.0.0:8081"

[storage]
commit_log_path = "data/commit_log.log"
checkpoint_path = "data/read.checkpoint.json"

[auth]
directory = "auth/tokens"
namespace_catalog_path = "data/namespace_catalog.sqlite"
namespace_catalog_read_only = true

The read daemon must point to the same commit log as the write daemon. If these diverge, your projections will not match the write path.

Step 4 - Start the write daemon

./target/release/assetcored-write --config write.toml

Verify it’s running:

curl -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  http://localhost:8080/v1/write/health

Expected: {"status": "healthy", ...}

Step 5 - Start the read daemon

./target/release/assetcored-read --config read.toml

Verify it’s running:

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  -H "x-assetcore-namespace: $ASSETCORE_NAMESPACE_ID" \
  http://localhost:8081/v1/read/health

Step 6 - Verify end-to-end

Send a test commit:

curl -X POST http://localhost:8080/v1/write/namespaces/${ASSETCORE_NAMESPACE_ID}/lifecycle \
  -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_state":"provisioned","reason":"deployment bootstrap"}'

curl -X POST http://localhost:8080/v1/write/namespaces/${ASSETCORE_NAMESPACE_ID}/commit \
  -H "Authorization: Bearer $ASSETCORE_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {"op": "CreateContainer", "args": {"container_id": 1, "kind": {"type": "balance"}, "owner": null, "policies": null}}
    ]
  }'

Read it back:

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://localhost:8081/v1/read/namespaces/${ASSETCORE_NAMESPACE_ID}/containers/1

Troubleshooting

”Address already in use”

Another process is using the port. Either stop that process or change the listen address.

”Permission denied” on commit log

The user running the daemon doesn’t have write access to the directory. Check ownership:

chown -R assetcore:assetcore /var/lib/assetcore

Read daemon shows old data

Check the freshness endpoint:

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://localhost:8081/v1/read/namespaces/${ASSETCORE_NAMESPACE_ID}/freshness

If world_seq is behind commit_log_world_seq, the read daemon is catching up. Monitor the lag metric.

Crash recovery

Both daemons recover automatically from their checkpoints on restart. No manual intervention needed.

Next steps

• Health and Metrics - Monitoring endpoints
• CLI Reference - Using acctl for operations