Docs / Actor platforms / Akka (Apache Pekko)

Akka (Apache Pekko)alpha

Run Motoko actors as Pekko Cluster Sharding entities, with state in Postgres.

Each actor key is an entity in Pekko Cluster Sharding, the open-source continuation of Akka. Pekko places it and delivers its messages one at a time; its state is stored in Postgres.

You also need the moxzi SDK and hosts bundles; see Actor platforms.

Prerequisites#

A JDK
coursier (cs)
Docker, for Postgres

Create and run a project#

moxzi host new akka hello
cd hello
ONCE=1 ./run.sh

Among the build and platform log lines, the demo prints Counter/1.inc() -> [1]. Run it again and it prints [2]: the host is a new process, and the actor's state comes back from the platform's store.

ONCE=1 exits after the demo. Without it, the host keeps running on port 8090 (set PORT to change it), and you can call any key:

curl -X POST localhost:8090/actors/Counter/2/method/inc \
  -H 'content-type: application/json' -d '[]'

--example ledger and --example saga work on Akka (Apache Pekko) too; see Examples.

The project#

Path	Contents
`actor.mo`	The `Counter` actor type. Each key `Counter/ID` is a separate actor
`host/`	moxzi's Akka (Apache Pekko) adapter. It's yours to change
`run.sh`	Builds the actor and the host, starts what Akka (Apache Pekko) needs, and runs the demo

Change actor.mo and run ./run.sh again. New keys use the new code. Existing keys keep their code until they're upgraded; host/README.md describes upgrades.

How it maps#

	Handled by
One message at a time per key	The sharded entity
Placement	Pekko Cluster Sharding
Actor state	Postgres, in a Docker container named `moxzi-hello-pg` on port 55432 that `run.sh` starts and leaves running. Set `DATABASE_URL` to use your own database, or `PG_PORT` to use another port
Durable timers	A `_timers` table in Postgres, checked every 200 ms. Each timer fires once even with several hosts

Remove the database container with docker rm -f moxzi-hello-pg when you're done.

Configuration#

Variable	Default	Effect
`PORT`	`8090`	The host's HTTP port
`MOXZI_HOST_TOKEN`	random	Token for the host's control endpoints (`/_moxzi/*`)
`DATABASE_URL`	a local container	Postgres connection string
`PG_PORT`	`55432`	Port for the local Postgres container. All projects use the same default, so only one can run at a time