atlas

Atlas

Source code for the default Cosmos SDK module registry, viewable online at atlas.cosmos.network.

Table of Contents

• Atlas
  • Table of Contents
  • Background
  • Usage
    • Server
    • API Documentation
    • Web App
    • Publishing
    • Action
  • Migrations
  • Local Development
  • Tests
  • License

Background

Atlas implements a Cosmos SDK module registry, where developers are able to publish and update modules. The registry provides a singular and holistic interface for application developers to discover Cosmos SDK modules when building their blockchain applications.

More information about the architecture, publishing and module configuration can be found under docs.

Dependencies

• Golang 1.15+
• migrate
• Node.js/npm
• Yarn
• Vue.js
• Docker/Docker-Compose

Usage

Atlas is composed of two primary components, the server and the web application. The server is responsible for providing a RESTful API, handling user authentication via Github OAuth and persisting modules and relevant data to PostgreSQL.

Further documentation can be found here.

Server

In order to start the Atlas server, you must provide a series of configuration values that may be defined in environment variables, a (TOML) configuration file or via CLI flags (in order of precedence). See the sample env or config files for all possible configurations.

$ atlas server --config=/path/to/atlas/config.toml

Note:

1. Atlas will look for environment variables defined in a .env file in the root directory. Any explicit environment variables defined will override those defined in this file.
2. Certain configuration values are not exposed or able to be provided via CLI flags.
3. All environment variables must be prefixed with ATLAS_*.

See --help for further documentation.

API Documentation

Atlas leverages Swagger to document its API. The documentation is compiled automatically via swag through annotated REST handlers. The compiled documentation resides in the docs/api directory and is served at /api/docs/.

The Swagger documentation can be recompiled as follows:

$ make update-swagger-docs

Web App

The Atlas web application is built using Vue.js and is contained in the web directory. The web application is executed as a separate process external from the Atlas API server. The webapp requires VUE_APP_ATLAS_API_ADDR to be populated in order to know how to speak with the Atlas API. This can be set as an explicit environment variable or populated in a .env file at the root of the web directory.

To run the webapp locally and watch for lives changes:

$ cd web && yarn serve

To build for production:

$ cd web && yarn build

Publishing

To publish a Cosmos SDK module, please see the publishing doc.

Action

To publish a Cosmos SDK module with github actions, please see the action doc.

Migrations

Atlas performs migrations through the migrate tool. The migrations are defined in db/migrations. In order to run migrations, you must provide a ATLAS_DATABASE_URL environment variable.

$ ATLAS_DATABASE_URL=... make migrate

Local Development

To run, test and experiment with Atlas in a local development environment, execute the following:

1. Start a postgres database using Docker:

   $ docker-compose up -d
   

2. Run migrations:

   $ ATLAS_DATABASE_URL="postgres://postgres:postgres@localhost:6432/postgres?sslmode=disable" make migrate
   

3. Populate your Atlas server config or root .env:

   ATLAS_DATABASE_URL=postgres://postgres:postgres@localhost:6432/postgres?sslmode=disable
   ATLAS_LOG_FORMAT=debug
   ATLAS_DEV=true
   ATLAS_GH_CLIENT_ID=...
   ATLAS_GH_CLIENT_SECRET=...
   ATLAS_ALLOWED_ORIGINS=http://localhost:8081
   
   # Testing session cookie (e.g. securecookie.GenerateRandomKey(32))
   ATLAS_SESSION_KEY=UIla7DSIVXzhvd9yHxexEExel9HQpSCQ+Rsn3y+e2Rs=
   

4. Start Atlas:

   $ atlas server
   

5. Start the webapp:

   $ cd web && yarn serve
   

Note, if you choose to run Atlas at a different listen address, be sure to populate VUE_APP_ATLAS_API_ADDR and ATLAS_ALLOWED_ORIGINS accordingly. Where the former is the listen address of the Atlas API server and the later is the address of the webapp (yarn will automatically allocate a free port).

Tests

Atlas performs all database relevant tests through a Docker Postgres instance. Executing the $ make test target will automatically start a Postgres Docker instance and populate all relevant environment variables. If you'd like to execute tests on a different Postgres instance, you must provide the ATLAS_MIGRATIONS_DIR and ATLAS_TEST_DATABASE_URL environment variables.

$ ATLAS_TEST_DATABASE_URL=... ATLAS_MIGRATIONS_DIR=... make test

License

• Apache License, Version 2.0