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.
The following steps will install the atlas
binary to your $GOBIN
directory.
$ go get github.com/infobloxopen/atlas-cli/atlas
You'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
$ make
Rather 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-application
Here'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 |
registry |
The Docker registry where application images are pushed | No | "" |
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 |
helm |
Initialize the application with helm charts | No | false |
expand |
Initialize the application with additional services based on a file | No | "" |
kind |
initialize the application with KinD support (optional, only applicable when helm charts are enabled) | No | false |
delve |
initialize the application with remote debug support (optional, only applicable when helm charts are enabled) | No | false |
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,KubeCluster
Images 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-version
To 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 -pubsub
Of course, you may include all the flags in the init-app
command.
atlas init-app -name=my-application -gateway -db -registry=infoblox -pubsub -health
Helm 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 start
This 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.local
to hosts file. You might execute command in terminal
echo "$(minikube ip) minikube.local" > /etc/hosts
or
echo "$(minikube ip) minikube.local" | sudo tee -a /etc/hosts
After that you can run targets from Makefile
make helm-install # to install your app in minikube
make helm-delete # to delete your app from minikube
and get access to API through minikube.local
. For example
curl minikube.local/NAME_YOUR_APP/v1/version
Generated 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 templating
Your 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.