Skip to content

GettingStarted.md

Latest commit

 

History

History
140 lines (105 loc) · 4.29 KB

GettingStarted.md

File metadata and controls

140 lines (105 loc) · 4.29 KB
Raw

Getting Started

This walkthrough starts a Colonies server, creates a colony with a user and an executor, and runs a first process - all from one machine.

1. Start a server

The quickest path is the all-in-one container, which bundles the server and an embedded PostgreSQL and generates all needed keys on first start:

docker run -d --name colonies -p 50080:50080 \
    -v colonies-data:/var/lib/postgresql/data \
    colonyos/colonies-allinone:latest
docker logs colonies

The log prints a server key, a colony key, and a user key. Other deployment layouts (external PostgreSQL, file storage, high availability) are covered in the Deployment Guide; installing the colonies CLI is covered in Installation.

2. Configure the CLI

Export the connection settings and the keys printed by the container:

export COLONIES_SERVER_HOST="localhost"
export COLONIES_SERVER_HTTP_PORT="50080"
export COLONIES_TLS="false"
export COLONIES_SERVER_PRVKEY="<server-private-key>"
export COLONIES_COLONY_NAME="dev"
export COLONIES_COLONY_PRVKEY="<colony-private-key>"
export COLONIES_PRVKEY="<user-private-key>"

With these set, most commands need no flags. Check the connection:

colonies server status

If you run the Compose postgres profile instead, ./scripts/generate-dev-env.sh writes all of this to .env; load it with set -a; . ./.env; set +a.

3. Create a colony and a user

A colony is a runtime environment owned by a colony key. Register the colony and a user (the ids are derived from the private keys; colonies security id --prvkey <key> prints the id for a key):

colonies colony add --name dev --colonyid <colony-id>
colonies user add --name myuser --userid <user-id> --email "" --phone ""

4. Register an executor

Executors execute processes. For this walkthrough the CLI itself will act as an executor. executor create generates a keypair, registers, and approves it in one step:

colonies executor create --name myexecutor --type cli --approve --keypath /tmp/executor.key --idpath /tmp/executor.id
colonies executor ls

5. Submit a function specification

A function specification declares what to run and the conditions for where it may run. examples/functions/sleep.json:

{
    "conditions": {
        "executortype": "cli"
    },
    "funcname": "sleep",
    "args": [
        "10"
    ]
}

Submit it:

colonies function submit --spec examples/functions/sleep.json

The process is now queued, waiting for an executor of type cli:

colonies process psw

6. Execute the process

A real executor would poll for assignments and run the function. Simulate that with the CLI, using the executor key created in step 4:

colonies process assign --prvkey $(cat /tmp/executor.key)
colonies process close -p <process-id>

assign pulls the waiting process and marks it RUNNING; close completes it as SUCCESS. Inspect the result:

colonies process pss
colonies process get -p <process-id>

Real executor implementations are built against the SDKs - see Implementing Executors and the Fibonacci tutorial for a Go executor, or the prebuilt executors at github.com/colonyos/executors.

Execution guarantees

Two conditions-level settings control what happens to stuck work:

  • maxexectime: maximum seconds a process may run after assignment (-1 means no limit). When exceeded, the process is unassigned and put back in the queue (or failed with "Maximum execution time limit exceeded" once maxretries is exhausted). Always set this for production workloads - it is the mechanism that recovers processes from crashed or disconnected executors.
  • maxwaittime: maximum seconds a process may wait in the queue. When exceeded, the process is closed as FAILED with the error "Maximum waiting time limit exceeded" (it remains visible via colonies process psf). A value of 0 or -1 means no limit.
  • maxretries: how many times a maxexectime timeout may be retried. -1 (the default) retries forever.

Next steps