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

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

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.

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

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.

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.

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

The Atlas web application is built using Vue.js and is contained in the web directory. The web application is served as a static resource from the same service as the API. It contains a .env file at the root which must contain a VUE_APP_ATLAS_API_ADDR environment variable that describes how to reach the Atlas API.

To build locally and watch for lives changes:

$ cd web && npm run build-watch

To build for production:

$ cd web && npm run build

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

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:

   # .env
   
   # Database and Atlas server options
   ATLAS_DATABASE_URL=postgres://postgres:postgres@localhost:6432/postgres?sslmode=disable
   ATLAS_LOG_FORMAT=debug
   ATLAS_DEV=true
   
   # GitHub OAuth
   ATLAS_GH_CLIENT_ID=...
   ATLAS_GH_CLIENT_SECRET=...
   ATLAS_GH_REDIRECT_URL=http://localhost:8080/api/v1/session/authorize
   
   # Testing session cookie (e.g. securecookie.GenerateRandomKey(32))
   ATLAS_SESSION_KEY=UIla7DSIVXzhvd9yHxexEExel9HQpSCQ+Rsn3y+e2Rs=

4. Start Atlas:

   $ atlas server

5. Watch for web app changes:

   $ cd web && npm run build-watch

Note, if you run Atlas with a custom listening address, be sure to update the VUE_APP_ATLAS_API_ADDR environment variable in web/.env and the ATLAS_GH_REDIRECT_URL.

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

• Apache License, Version 2.0