This command-line tool helps developers become productive on Atlas. It aims to provide a better development experience by reducing the initial time and effort it takes to build applications.
These instructions will help you get the Atlas command-line tool up and running on your machine.
Please install the following dependencies before running the Atlas command-line tool.
Protobuf generator for go
go get -u github.com/golang/protobuf/protoc-gen-goFor more details visit protoc-gen-go.
This is a dependency management tool for Go. You can install dep with Homebrew:
$ brew install depMore detailed installation instructions are available on the GitHub repository.
Bootstrapped applications use golang-migrate for database migrations. You can install the migrate binary with the standard Go toolchain:
$ go get -u -d github.com/golang-migrate/migrate/cli github.com/lib/pq
$ apt install libc6-dev #it is necessary for a successful build
$ go build -tags 'postgres' -o /usr/local/bin/migrate github.com/golang-migrate/migrate/cli
See the official golang-migrate GitHub repository for more information about this tool.
The following steps will install the atlas binary to your $GOBIN directory.
$ go get github.com/infobloxopen/atlas-cli/atlasYou're all set! Alternatively, you can clone the repository and install the binary manually.
$ git clone https://github.com/infobloxopen/atlas-cli.git
$ cd atlas-cli
$ makeRather than build applications completely from scratch, you can leverage the command-line tool to initialize a new project. This will generate the necessary files and folders to get started.
$ atlas init-app -name=my-application
$ cd my-applicationHere's the full set of flags for the init-app command.
| Flag | Description | Required | Default Value |
|---|---|---|---|
name |
The name of the new application | Yes | N/A |
db |
Bootstrap the application with PostgreSQL database integration | No | false |
gateway |
Initialize the application with a gRPC gateway | No | false |
health |
Initialize the application with internal health checks | No | false |
metrics |
Initialize the application with gRPC Prometheus metrics | No | true |
pubsub |
Initialize the application with a atlas-pubsub example | No | false |
registry |
The Docker registry where application images are pushed | No | "" |
helm |
Initialize the application with helm charts | No | false |
expand |
Initialize the application with additional services based on a file | No | "" |
You can run atlas init-app --help to see these flags and their descriptions on the command-line.
# generates an application with a grpc gateway
atlas init-app -name=my-application -gateway# generates an application with a postgres database
atlas init-app -name=my-application -db# specifies a docker registry
atlas init-app -name=my-application -registry=infoblox# generates an application with additional services
# the input file (expand.txt in the example below)
# is a list of strings (letters only), one service name on each line
atlas init-app -name=my-application -expand=expand.txt -db=true# example `expand.txt` file for use with -expand option
# Each line must either be a single string of letters only,
# or two strings separated by a single comma. The latter option
# Is for the use case where the user wants a customized pluralization
# of a word. In the example below, "Artifacts" will pluralize to
# "Artifactss", and "Kubernetes" will pluralize to "KubeCluster"
# In general, the best practice for object names should be
# either <singular> or <singular,plural>
Artifacts
AwsInstance
Kubernetes,KubeClusterImages names will vary depending on whether or not a Docker registry has been provided.
# docker registry was provided
registry-name/image-name:image-version# docker registry was not provided
image-name:image-versionTo run the pubsub example ensure you run the application with the correct configuration by passing the pubsub server address. For more info atlas-pubsub
# generates an application with a pubsub example
atlas init-app -name=my-application -pubsubOf course, you may include all the flags in the init-app command.
atlas init-app -name=my-application -gateway -db -registry=infoblox -pubsub -healthHelm charts allow you to configure the manifest and deploy it in the Kubernetes cluster.
For use helm in minikube you have to:
- Install minikube and run:
minikube startThis command will configure access to the cluster in the minikube;
- Install Tiller in the cluster. After configuring access to the cluster, execute:
helm init- Work with the Docker daemon locally. You might execute following command in terminal
eval $(minikube docker-env)- Add host name
minikube.localto hosts file. You might execute command in terminal
echo "$(minikube ip) minikube.local" > /etc/hostsor
echo "$(minikube ip) minikube.local" | sudo tee -a /etc/hostsAfter that you can run targets from Makefile
make helm-install # to install your app in minikube
make helm-delete # to delete your app from minikubeand get access to API through minikube.local. For example
curl minikube.local/NAME_YOUR_APP/v1/versionGenerated atlas projects use viper, a complete configuration solution that allows an application to run from different environments. Viper also provides precedence order which is in the order as below.
By default if you don't change anything your application will run with the values in config.go
go run cmd/server/*.go --database.port 5432
export DATABASE_PORT=5432
go run cmd/server/*.go
Change the configuration for defaultConfigDirectory and defaultConfigFile to point to your configuration file. You can either change it in config.go, passing it as environment variables, or flags.
go run cmd/server/*.go --config.source "some/path/" --config.file "config_file.yaml"
- Copy config.go and add it to your project under cmd/server/config.go
- Update config.go by setting all your default values
- Add the following snippet of code inside your main.go that will allow you to initilize all the viper configuration.
func init() {
pflag.Parse()
viper.BindPFlags(pflag.CommandLine)
viper.AutomaticEnv()
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
viper.AddConfigPath(viper.GetString("config.source"))
if viper.GetString("config.file") != "" {
log.Printf("Serving from configuration file: %s", viper.GetString("config.file"))
viper.SetConfigName(viper.GetString("config.file"))
if err := viper.ReadInConfig(); err != nil {
log.Fatalf("cannot load configuration: %v", err)
}
} else {
log.Printf("Serving from default values, environment variables, and/or flags")
}
resource.RegisterApplication(viper.GetString("app.id"))
resource.SetPlural()
}- To get or set viper configuration inside your code use the following methods:
// Retrieving a string
viper.GetString("database.address")
// Retrieving a bool
viper.GetBool("database.enable")Contributions to the Atlas CLI are welcome via pull requests and issues. If you're interested in making changes or adding new features, please take a minute to skim these instructions.
The templates/ directory contains a set of Go templates. When the Atlas CLI bootstraps a new application, it uses these templates to render new application files.
This project uses go-bindata to package the Go templates and atlas source files together into a single binary. If your changes add or update templating, you need to regenerate the template bindata by running this command:
make templatingYour templating changes will take effect next time you run the atlas binary.
The Atlas CLI integration tests ensure that new changes do not break exists features. To run the Atlas CLI unit and integration tests locally, set e2e=true in your environment.
make test-with-integration
If you wish to add a new command to the Atlas CLI, please take a look at the command interface. This interface is intended to make adding new commands as minimally impactful to existing functionality.
To start out, consider looking at the bootstrap command's implementation of this interface.