Skip to content

Getting started with XDN

This page explains how to deploy a blackbox stateful service on an existing XDN provider.

Install the CLI

Install the xdn CLI with a single command — it downloads the right binary for your OS and architecture, verifies its SHA-256 checksum, and installs it to ~/.local/bin:

curl -fsSL https://xdn.cs.umass.edu/install | sh

Check that it runs:

xdn --help
Other ways to get it

Inspect the script first with curl -fsSL https://xdn.cs.umass.edu/install | less, grab a binary directly from the releases page, or build from source: git clone https://github.com/fadhilkurnia/xdn && cd xdn && ./bin/build_xdn_cli.sh.

Deploy a blackbox service

XDN places your service's replicas at edge locations close to your users — across AWS Regions and Local Zones worldwide. Here are the available edge locations:

Finally, launch a blackbox stateful service on XDN. Let's use bookcatalog as the service name. 

xdn launch bookcatalog \
   --image=fadhilkurnia/xdn-bookcatalog \ 
   --port=80 \
   --consistency=linearizable \
   --deterministic=true \
   --state=/app/data/
If successful, you will see the following output below, then you can access the stateful service by visiting http://bookcatalog.xdnapp.com/. 
Launching bookcatalog service with the following configuration:
  docker image  : fadhilkurnia/xdn-bookcatalog
  http port     : 80
  consistency   : linearizable
  deterministic : true
  state dir     : /app/data/

The service is successfully launched 🎉🚀
Access your service at the following permanent URL:
  > http://bookcatalog.xdnapp.com/


Retrieve the service's replica locations with this command:
  xdn service info bookcatalog
Destroy the replicated service with this command:
  xdn service destroy bookcatalog

Let's dechiper what just happened when we deploy a stateful service with the command above.

  • Blackbox Service. XDN handles arbitrary stateful service, the --image specifies the Docker image of the containerized service. XDN doesn't need to know how and with what programming language the service was implemented.
  • HTTP Interface. XDN acts as proxy for all incoming HTTP request, so XDN can coordinate the requests among the replicas. The --port option specifies the port where the service listen to incoming HTTP requests. When unspecified, XDN asssumes the default HTTP port of 80.
  • Service Properties. The --deterministic option specifies whether the web service is deterministic or not. Other than determinism, XDN allows developer to specify other properties of the service and its requests so XDN can use an optimized replication protocol, depending on the service's properties.
  • Consistency Model. The --consistency option specifies the consistency model the developer wants for the replicated service. The default value is linearizable. Check out this page to see how to use different consistency model.
  • State Directory. The --state option specifies the directory where the web service stores its state. For example, it is commonly /var/lib/mysql in MySQL and /var/lib/pgsql/data in PostgreSQL. When not specified, XDN will snapshot the entire data in the container /.
  • XDN Provider. Here, we are using an existing XDN provider, accessible at xdnapp.com. You can use another XDN Provider using --control-plane=<control_plane_url> option. Alternatively, you can be your own XDN Provider! check out this page.

Deploy using a service declaration file

Instead of passing each property as a separate CLI flag, you can declare the whole service in a YAML file and launch it with --file, which keeps the service definition versionable. Here is the bookcatalog service from above, written as bookcatalog.yaml:

# bookcatalog.yaml
---
name: bookcatalog
image: fadhilkurnia/xdn-bookcatalog
port: 80
consistency: linearizability
deterministic: true
state: /app/data/

Then launch it with: 

xdn launch bookcatalog --file=bookcatalog.yaml

This is equivalent to the xdn launch bookcatalog --image=… --state=… command shown earlier.

A declaration file really shines when a service is made of several containers — a frontend, a backend, and a database, for example. See Deploy a multi-container service for how to declare and launch one.

Other example services

XDN can replicate any stateful service, as long as it exposes a request-response HTTP interface and keeps its safety-critical state on disk. Other than the fadhilkurnia/xdn-bookcatalog Docker image that we use previously, we have prepared Docker images for other stateful services, as can be seen below.

Docker Image Description Example Launch Command
fadhilkurnia/xdn-bookcatalog Book catalog web app, storing updatable list of books.
Tech: Go, SQLite.		 
xdn launch alice-catalog \
     --image=fadhilkurnia/xdn-bookcatalog \
     --state=/data/ \
     --deterministic
fadhilkurnia/xdn-bookcatalog-nd Book catalog web app that is non-deterministic because it stores the update timestamp.
Tech: Go, SQLite.		 
xdn launch bob-catalog \
    --image=fadhilkurnia/xdn-bookcatalog-nd \
    --state=/data/
fadhilkurnia/xdn-tpcc App for a wholesale parts supplier that owns multiple warehouse, implementing
the TPC-C benchmark.
Tech: Python, SQLite.		 
xdn launch charlie-tpcc \
    --image=fadhilkurnia/xdn-tpcc \
    --state=/app/data/
fadhilkurnia/xdn-todo Todo application, enabling users to list and modify
their todo items.
Tech: Go, SQLite.		 
xdn launch dave-todo \
    --image=fadhilkurnia/xdn-todo \
    --state=/app/data/
fadhilkurnia/xdn-webkv Key-value store with a simple REST API
(YCSB-style GET/PUT/POST/DELETE /api/kv/:key).
Tech: Rust, RocksDB.		 
xdn launch mykv \
    --image=fadhilkurnia/xdn-webkv \
    --state=/app/data/ \
    --deterministic
fadhilkurnia/xdn-noop No-op baseline service: returns 200 ok
immediately with no state or work. Useful to
measure XDN's coordination overhead.
Tech: Go.		 
xdn launch noop \
    --image=fadhilkurnia/xdn-noop
fadhilkurnia/xdn-hotel-reservation Hotel reservation app — a consolidated port of
DeathStarBench's hotel reservation (frontend + MongoDB).
Tech: Go, MongoDB.		 Multi-container; launch from a declaration file
(see Deploy a multi-container service): 
xdn launch hotel \
    --file=hotel-reservation.yaml
fadhilkurnia/xdn-moviereview Consolidated DeathStarBench movie-review service:
movies, users, ratings, and reviews.
Multi-container: frontend + MongoDB.
Tech: Go, MongoDB.		 Multi-container; launch from a declaration file
(see Deploy a multi-container service): 
xdn launch moviereview \
    --file=moviereview.yaml
fadhilkurnia/xdn-smallbank SmallBank OLTP benchmark: savings/checking
accounts with money-moving transactions.
Tech: Go, SQLite.		 
xdn launch bank \
    --image=fadhilkurnia/xdn-smallbank \
    --state=/app/data/ \
    --deterministic
fadhilkurnia/xdn-ecommerce Webshop OLTP service: products, customers,
carts, and orders (browse, add to cart, checkout).
Tech: Go, SQLite.		 
xdn launch shop \
    --image=fadhilkurnia/xdn-ecommerce \
    --state=/app/data/ \
    --deterministic
fadhilkurnia/xdn-socialnetwork Consolidated DeathStarBench social network:
users, posts, follows, and timelines.
Multi-container: frontend + MongoDB.
Tech: Go, MongoDB.		 Multi-container; launch from a declaration file
(see Deploy a multi-container service): 
xdn launch socialnetwork \
    --file=socialnetwork.yaml
fadhilkurnia/xdn-seats SEATS airline-ticketing benchmark: airports,
flights, customers, and seat reservations.
Tech: Go, SQLite.		 
xdn launch seats \
    --image=fadhilkurnia/xdn-seats \
    --state=/app/data/ \
    --deterministic