Skip to main content
Version: 3.0.0

Getting Started

Installation​

The easiest way to install the Anchor Platform is to pull the docker image.

docker pull stellar/anchor-platform:latest

Set Up the Development Environment​

In this guide we'll use docker compose for simplicity, but you can run the Anchor Platform using other tools that support docker as well, such as minikube or a full-blown kubernetes cluster.

Let's create a minimal compose file to get started.

# docker-compose.yml
services:
  sep-server:
    image: stellar/anchor-platform:latest
    command: --sep-server
    ports:
      - "8080:8080"
    env_file:
      - ./dev.env
    volumes:
      - ./config:/home
  platform-server:
    image: stellar/anchor-platform:latest
    command: --platform-server
    ports:
      - "8085:8085"
    env_file:
      - ./dev.env
    volumes:
      - ./config:/home

The --sep-server option tells the Anchor Platform to make the API endpoints defined by the SEPs you've enabled via configuration available on port 8080.

The --platform-sever option makes the Platform API available, which is the backend API your service(s) will use to communicate with the Anchor Platform. It will be available on port 8085

Configuration​

The Anchor Platform supports two approaches for configuration:

  • using environment variables
  • using a YAML configuration file

One or a combination of both approaches can be used. Nested variables in the YAML file are expressed using underscores or dots (_, .) when using environment variables. We'll demonstrate both approaches here, but use enviroment variables exclusively in subsequent sections. See the full set of configuration options in the Anchor Platform's default values file.

info

The Anchor Platform does not allow application secrets in the YAML configuration file. Instead, application secrets, which all have the SECRET_ prefix, must be specified in the environment.

Lets create the environment file specified in our docker compose file.

touch dev.env

And if you're using a YAML configuration file, lets create that too.

mkdir config
touch config/dev.services.yaml

You'll need to inform the Anchor Platform where it can find your config file. So lets add an environment variable for that.

# dev.env
STELLAR_ANCHOR_CONFIG=/home/dev.services.yaml

Specify the configuration schema version in your YAML file.

# dev.services.yaml
version: 1

Changing Port of the Platform Server​

For example, let's change port of the platform server.

Using environment variables, this is simply:

# dev.env
PLATFORM_SERVER_PORT=8085

Or if using YAML configuration:

# dev.services.yaml
platform_server:
  port: 8085

Specify Your Service's Assets​

Lets add the assets your Anchor Platform deployment will utilize. This configuration is specified in a YAML file. If you're only using the Anchor Platform for hosting a SEP-1 stellar.toml file or for running SEP-10 Stellar Authentication, you can skip this step.

touch config/dev.assets.yaml

In this guide we'll build anchor services for Circle's USDC on Stellar's test network. Update the above values based on the assets you'll be issuing. Make sure to specify the testnet issuer in your development file, and create your own distribution_account using a tool like Stellar Lab. The distribution_account will be used by your clients as the destination account for payments to your service.

# dev.assets.yaml
assets:
  - schema: stellar
    code: USDC
    issuer: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
    distribution_account: GBLSAHONJRODSFTLOV225NZR4LHICH63RIFQTQN37L5CRTR2IMQ5UEK7
    significant_decimals: 2

This file needs to be referenced in our configuration so the Anchor Platform can find it.

Using environment variables:

# dev.env
ASSETS_TYPE=file
ASSETS_VALUE=/home/dev.assets.yaml

Using a YAML file:

# dev.services.yaml
assets:
  type: file
  value: /home/dev.assets.yaml

Add Data Persistence​

The Anchor Platform supports PostgreSQL and Aurora PostgreSQL for use in production, but also supports H2 or SQLite for use in development. For managing migrations, the Anchor Platform uses Flyway. The latest version of PostgreSQL supported by Flyway is PostgreSQL 14.

Before we move forward, let's add a database to our development environment so the transactions we initiate persist after stopping the service.

A database is only needed if using the Anchor Platform to facilitate transactions.

# docker-compose.yml
version: "3.8"
services:
  sep-server:
    image: stellar/anchor-platform:latest
    command: --sep-server
    env_file:
      - ./dev.env
    volumes:
      - ./config:/home
    ports:
      - "8080:8080"
    depends_on:
      - db
  platform-server:
    image: stellar/anchor-platform:latest
    command: --platform-server
    env_file:
      - ./dev.env
    volumes:
      - ./config:/home
    ports:
      - "8085:8085"
    depends_on:
      - db
  db:
    image: postgres:14
    ports:
      - "5432:5432"
    env_file:
      - ./dev.env
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql

Now let's update our environment so the platform server can connect to the database server.

# dev.env
DATA_TYPE=postgres
DATA_SERVER=db
DATA_DATABASE=platform
DATA_FLYWAY_ENABLED=true

SECRET_DATA_USERNAME=postgres
SECRET_DATA_PASSWORD=password

POSTGRES_USER=postgres
POSTGRES_PASSWORD=password

If you're using YAML configuration instead, the POSTGRES_ environment variables should always be in the environment, as they're for your database server, not the Anchor Platform. The secrets must also be specified in environment.

# dev.services.yaml
data:
  type: postgres
  server: db
  database: platform
  flyway_enabled: true

We have to create the platform database before the platform server can connect to it, so let's make a script to create our database.

touch init.sql
-- init.sql
CREATE DATABASE platform;

Try to run the platform server in addition to the database.

docker compose up

You should see the logs reporting a successful connection to the postgres database.

Configure Platform API Authentication​

To facilitate cross-border payments or deposit & withdrawal transactions, your business will need to fetch and update transaction records from the Anchor Platform's internal API. Currently, the --sep-server option makes public SEP APIs, while internal Platform API available on the Platform server, started by --platform-server option. Business should make Platform Server accessible only in the internal network, however it's possible to add authentication for accessing the internal Platform API.

Add the following environment variables.

# dev.env
PLATFORM_API_BASE_URL=http://platform-server:8085
PLATFORM_API_AUTH_TYPE=jwt
SECRET_PLATFORM_API_AUTH_SECRET=[your jwt encryption key]

When making requests to the Platform API, add a JWT signed by the secret defined in your environment to the Authorization header as a bearer token.

PLATFORM_API_BASE_URL uses platform instead of localhost as the host because you'll be making requests to the Platform API within the local network created by docker compose. When configuring your service in a staging or production environment, make sure to update your service urls.

Passing JVM flags​

Anchor Platform uses JVM to run. Sometimes, it's desired to change JVM flags to run the service. To do so, set environmental variable JVM_FLAGS to appropriate value

# dev.env
JVM_FLAGS="-Xms256m -Xmx2048m"
tip

If you need to pass environment variable from your machine to container, you should use environment compose option to set variables instead. Here's an example of using keystore from your local machine in the container:

# docker-compose.yml
version: "3.8"
services:
  sep-server:
    image: stellar/anchor-platform:latest
    command: --sep-server
    env_file:
      - ./dev.env
    environment:
      JVM_FLAGS: -Djavax.net.ssl.trustStore=/keystore.jks -Djavax.net.ssl.trustStorePassword=${KEYSTORE_PASSWORD}
    volumes:
      - ${KEYSTORE_LOCATION}:/keystore.jks
# ...

Where KEYSTORE_LOCATION is local keystore location and KEYSTORE_PASSWORD is local keystore password.