Source code for the default Cosmos SDK module registry, viewable online at atlas.cosmos.network.
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.
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:
- 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. - Certain configuration values are not exposed or able to be provided via CLI flags.
- 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:
-
Start a postgres database using Docker:
$ docker-compose up -d
-
Run migrations:
$ ATLAS_DATABASE_URL="postgres://postgres:postgres@localhost:6432/postgres?sslmode=disable" make migrate
-
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=
-
Start Atlas:
$ atlas server
-
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