Improve building tools and docs

Makefile

@@ -180,6 +180,8 @@ bins_nothrift: fmt lint copyright cadence-cassandra-tool cadence-sql-tool cadenc
 
 bins: thriftc bins_nothrift
 
+tools: cadence-cassandra-tool cadence-sql-tool cadence
+
 test: bins
 	@rm -f test
 	@rm -f test.log
@@ -260,23 +262,23 @@ clean:
 	rm -f cadence-cassandra-tool
 	rm -Rf $(BUILD)
 
-install-schema: bins
+install-schema: cadence-cassandra-tool
 	./cadence-cassandra-tool --ep 127.0.0.1 create -k cadence --rf 1
 	./cadence-cassandra-tool --ep 127.0.0.1 -k cadence setup-schema -v 0.0
 	./cadence-cassandra-tool --ep 127.0.0.1 -k cadence update-schema -d ./schema/cassandra/cadence/versioned
 	./cadence-cassandra-tool --ep 127.0.0.1 create -k cadence_visibility --rf 1
 	./cadence-cassandra-tool --ep 127.0.0.1 -k cadence_visibility setup-schema -v 0.0
 	./cadence-cassandra-tool --ep 127.0.0.1 -k cadence_visibility update-schema -d ./schema/cassandra/visibility/versioned
 
-install-schema-mysql: bins
+install-schema-mysql: cadence-sql-tool
 	./cadence-sql-tool --ep 127.0.0.1 create --db cadence
 	./cadence-sql-tool --ep 127.0.0.1 --db cadence setup-schema -v 0.0
 	./cadence-sql-tool --ep 127.0.0.1 --db cadence update-schema -d ./schema/mysql/v57/cadence/versioned
 	./cadence-sql-tool --ep 127.0.0.1 create --db cadence_visibility
 	./cadence-sql-tool --ep 127.0.0.1 --db cadence_visibility setup-schema -v 0.0
 	./cadence-sql-tool --ep 127.0.0.1 --db cadence_visibility update-schema -d ./schema/mysql/v57/visibility/versioned
 
-install-schema-postgres: bins
+install-schema-postgres: cadence-sql-tool
 	./cadence-sql-tool --ep 127.0.0.1 -p 5432 -u postgres -pw cadence --pl postgres create --db cadence
 	./cadence-sql-tool --ep 127.0.0.1 -p 5432 -u postgres -pw cadence --pl postgres --db cadence setup -v 0.0
 	./cadence-sql-tool --ep 127.0.0.1 -p 5432 -u postgres -pw cadence --pl postgres --db cadence update-schema -d ./schema/postgres/cadence/versioned
@@ -287,7 +289,7 @@ install-schema-postgres: bins
 start: bins
 	./cadence-server start
 
-install-schema-cdc: bins
+install-schema-cdc: cadence-cassandra-tool
 	@echo Setting up cadence_active key space
 	./cadence-cassandra-tool --ep 127.0.0.1 create -k cadence_active --rf 1
 	./cadence-cassandra-tool --ep 127.0.0.1 -k cadence_active setup-schema -v 0.0

README.md

@@ -19,10 +19,15 @@ We highly recommend that you use [Cadence service docker](docker/README.md) to r
 
 Try out the sample recipes for [Go](https://github.com/uber-common/cadence-samples) or [Java](https://github.com/uber/cadence-java-samples) to get started.
 
-### Use CLI
+### Use CLI Tools
+Use [Cadence command-line tool](tools/cli/README.md) to perform various tasks on Cadence server cluster
 
-Try out [Cadence command-line tool](tools/cli/README.md) to perform various tasks on Cadence
+For [manual setup or upgrading](docs/persistence.md) server schema --
 
+* If server runs with Cassandra, Use [Cadence Cassandra tool](tools/cassandra/README.md) to perform various tasks on database schema of Cassandra persistence
+* If server runs with SQL database, Use [Cadence SQL tool](tools/sql/README.md) to perform various tasks on database schema of SQL based persistence
+
+TIPS: Run `make tools` to build all tools mentioned above. 
 ### Use Cadence Web
 
 Try out [Cadence Web UI](https://github.com/uber/cadence-web) to view your workflows on Cadence.

docker/README.md

@@ -97,4 +97,6 @@ docker run -e CASSANDRA_SEEDS=10.x.x.x                  -- csv of cassandra serv
 Note that each env variable has a default value, so you don't have to specify it if the default works for you. 
 For more options to configure the docker, please refer to `config_template.yaml`.
 
-For <tag>, you may not use `auto-setup` images for production deployment. See the above explanation. 
+For `<tag>`, use `auto-setup` images only for first initial setup, and use regular ones for production deployment. See the above explanation about `auto-setup`. 
+
+When upgrading, follow the release instrusctions if version upgrades require some configuration or schema changes. 

tools/cassandra/README.md

@@ -9,7 +9,7 @@ make install-schema
 ## For production
 
 ### Create the binaries
-- Run `make bins`
+- Run `make cadence-cassandra-tool`
 - You should see an executable `cadence-cassandra-tool`
 
 ### Do one time database creation and schema setup for a new cluster

tools/cli/README.md

@@ -1,7 +1,7 @@
 Documentation for the Cadence command line interface is located at our [main site](https://cadenceworkflow.io/docs/cli/).
 
 ## Quick Start
-Run `make bins` from the project root. You should see an executable file called `cadence`. Try a few example commands to 
+Run `make cadence` from the project root. You should see an executable file called `cadence`. Try a few example commands to 
 get started:   
 `./cadence` for help on top level commands and global options   
 `./cadence domain` for help on domain operations  

tools/sql/README.md

@@ -11,7 +11,7 @@ SQL_USER=$USERNAME SQL_PASSWORD=$PASSWD make install-schema-mysql
 ## For production
 
 ### Create the binaries
-- Run `make bins`
+- Run `make cadence-sql-tool`
 - You should see an executable `cadence-sql-tool`
 - Cadence officially support MySQL and Postgres for SQL. 
 - For other SQL database, you can add it easily as we do for MySQL/Postgres following our code in sql-extensions