diff --git a/doc/source/dev/install.rst b/doc/source/dev/install.rst index 4d85f55..ef5dfbd 100755 --- a/doc/source/dev/install.rst +++ b/doc/source/dev/install.rst @@ -157,13 +157,16 @@ Database Setup # exit ------------------------------------ -Modify etc/craton-api-conf.sample +Create etc/craton-api-conf.dev ------------------------------------ +* Copy the sample config in the etc directory to make a development config file. + + # cp craton-api-conf.sample craton-api-conf.dev * Make api_paste_config use a fully qualified path (not relative). This will be specific for your machine -.. note:: Make sure you have the proper path for craton-api-conf.sample +.. note:: Make sure you have the proper path for craton-api-conf.dev # api_paste_config=/home/cratonuser/craton/etc/craton-api-paste.ini @@ -181,13 +184,11 @@ Run dbsync * Make sure to run dbsync to get the db tables created:: - # craton-dbsync --config-file=etc/craton - -api-conf.sample version - # craton-dbsync --config-file=etc/craton - -api-conf.sample upgrade + # craton-dbsync --config-file=etc/craton-api-conf.dev version + # craton-dbsync --config-file=etc/craton-api-conf.dev upgrade * Make sure to run dbsync bootstrap to create initial project and root user:: - # craton-dbsync --config-file=etc/craton-api-conf.sample bootstrap + # craton-dbsync --config-file=etc/craton-api-conf.dev bootstrap Note: The above command outputs user, project-id and API key to use with python-cratonclient to interact with craton server. @@ -198,8 +199,7 @@ Start the API Service * To start the API service, run the following command:: - # craton-api --config-file=etc/ - craton-api-conf.sample + # craton-api --config-file=etc/craton-api-conf.dev * Some examples of API calls are as below: @@ -209,7 +209,7 @@ Create a Region --------------- * In order to create the region, export the IP address you set in - /etc/craton-api-conf.sample:: + /etc/craton-api-conf.dev:: # export MY_IP=xxx.xxx.xxx.xxx @@ -267,6 +267,44 @@ Get a particular host -H "X-Auth-User: demo" \ -H "X-Auth-Project: 717e9a216e2d44e0bc848398563bda06" +----------------------- +Using wrapper functions +----------------------- + +Some wrapper functions have been included in craton/tools to quickly build, reload, populate, and query craton. + +* To load the wrapper functions, run the following in the craton parent directory:: + + # source tools/wrapper-functions.sh + +* To start craton directly, run the following from the craton parent directory:: + + # craton-direct-start + +* The following environment variables must be exported for working with the craton API server:: + + * CRATON_URL + * OS_PROJECT_ID + * OS_USERNAME + * OS_PASSWORD + +* You can search the logs for these values or run:: + + # export eval $(craton-direct-env) + +* Populate craton with fake data by running:: + + # craton-fake-data + +* Run API calls against craton with the following wrappers:: +.. note:: *Requires the installation of httpie* + + # craton-post v1/regions name=HKG + # craton-get v1/hosts + # craton-put v1/hosts/3 device_type=container + # craton-put v1/hosts/3/variables foo=47 bar:='["a", "b", "c"]' + # craton-delete v1/hosts/4 + ------------- Running Tests ------------- diff --git a/doc/source/docker-install.rst b/doc/source/docker-install.rst index 4fe664e..7774449 100755 --- a/doc/source/docker-install.rst +++ b/doc/source/docker-install.rst @@ -89,6 +89,35 @@ Calling into Craton $ curl -i "http://${ContainerIP}:7780/v1/hosts?region_id=1" -H "Content-Type: application/json" -H "X-Auth-Token: ${CRATON_API_KEY}" -H "X-Auth-User: ${CRATON_USERNAME}" -H "X-Auth-Project: ${CRATON_PROJECT_ID}" +----------------------- +Using wrapper functions +----------------------- + +*Some wrapper functions have been included in craton/tools to quickly build, reload, populate, and query craton. +* To load the wrapper functions, run the following in the craton parent directory:: + + # source tools/wrapper-functions.sh + +* To quick start and populate craton in docker, run the following from the craton parent directory:: + + # craton-docker-start + +* In order to interact with craton, export the bootstrap credentials by running:: + + # export eval $(craton-docker-env) + +* Populate craton with fake data by running:: + + # craton-fake-data + +* Run API calls against craton with the following wrappers:: +.. note:: *Requires the installation of httpie* + + # craton-post v1/regions name=HKG + # craton-get v1/hosts + # craton-put v1/hosts/3 device_type=container + # craton-put v1/hosts/3/variables foo=47 bar:='["a", "b", "c"]' + # craton-delete v1/hosts/4 ------------------- Command Cheat-Sheet diff --git a/tools/wrapper-functions.sh b/tools/wrapper-functions.sh new file mode 100644 index 0000000..2af3ff6 --- /dev/null +++ b/tools/wrapper-functions.sh @@ -0,0 +1,141 @@ + +# Example usage. Note that we simply pass through httpie conventions, +# such as nested JSON with := +# (https://github.com/jkbrzt/httpie#non-string-json-fields) +# +# Run from Craton parent directory +# $ source tools/wrapper-functions.sh +# +# For Docker quick start: +# $ craton-docker-start +# $ eval $(craton-docker-env) +# +# Direct env quick start: +# $ craton-direct-start +# $ eval $(craton-direct-env) +# +# Populate with fake data: +# $ craton-fake-data +# +# API calls: +# $ craton-post v1/regions name=HKG +# $ craton-get v1/hosts +# $ craton-put v1/hosts/3 device_type=container +# $ craton-put v1/hosts/3/variables foo=47 bar:='["a", "b", "c"]' +# $ craton-delete v1/hosts/4 + +# NOTE assumes the installation of httpie so that the http command is available! + +fix-url() { + [[ "$1" =~ ^http ]] && echo $1 || echo "${CRATON_URL}/${1}" +} + +craton-get() { + http "$(fix-url $1)" \ + "Content-Type:application/json" \ + "X-Auth-Token:${OS_PASSWORD}" \ + "X-Auth-User:${OS_USERNAME}" \ + "X-Auth-Project:${OS_PROJECT_ID}" +} + +craton-post() { + http POST "$(fix-url $1)" \ + "Content-Type:application/json" \ + "X-Auth-Token:${OS_PASSWORD}" \ + "X-Auth-User:${OS_USERNAME}" \ + "X-Auth-Project:${OS_PROJECT_ID}" \ + "${@:2}" +} + +craton-put() { + http PUT "$(fix-url $1)" \ + "Content-Type:application/json" \ + "X-Auth-Token:${OS_PASSWORD}" \ + "X-Auth-User:${OS_USERNAME}" \ + "X-Auth-Project:${OS_PROJECT_ID}" \ + "${@:2}" +} + +craton-delete() { + http DELETE "$(fix-url $1)" \ + "Content-Type:application/json" \ + "X-Auth-Token:${OS_PASSWORD}" \ + "X-Auth-User:${OS_USERNAME}" \ + "X-Auth-Project:${OS_PROJECT_ID}" \ + "${@:2}" +} + +_craton-extract-env() { + echo OS_PROJECT_ID=$(echo "$1" | grep 'ProjectId' | awk '{print $2}' | tr -d '\r') + echo OS_USERNAME=$(echo "$1" | grep 'Username' | awk '{print $2}' | tr -d '\r') + echo OS_PASSWORD=$(echo "$1" | grep 'APIKey' | awk '{print $2}' | tr -d '\r') +} + +craton-docker-env() { + _craton-extract-env "$(docker logs craton-api)" + CRATON_PORT=$(sed -nr "/^\[api\]/ { :l /^port[ ]*=/ { s/.*=[ ]*//; p; q;}; n; b l;}" etc/craton-api-conf.sample) + echo CRATON_URL=http://$(docker inspect --format '{{ .NetworkSettings.IPAddress }}' craton-api):${CRATON_PORT} +} + +craton-direct-env() { + _craton-extract-env "$(craton-dbsync --config-file=etc/craton-api-conf.dev bootstrap)" + CRATON_PORT=$(sed -nr "/^\[api\]/ { :l /^port[ ]*=/ { s/.*=[ ]*//; p; q;}; n; b l;}" etc/craton-api-conf.dev) + echo CRATON_URL=http://$(sed -nr "/^\[api\]/ { :l /^host[ ]*=/ { s/.*=[ ]*//; p; q;}; n; b l;}" etc/craton-api-conf.dev):${CRATON_PORT} +} + +craton-direct-start() { + # NOTE(jimbaker) Assumes MySQL user 'craton' is setup with password 'craton'!!! + + cat </dev/null + do + echo "Waiting for API server"; sleep 1 + done + + python3 tools/generate_fake_data.py \ + --url $CRATON_URL/v1 \ + --user $OS_USERNAME --project $OS_PROJECT_ID --key $OS_PASSWORD + + craton-get v1/regions +} + +craton-docker-start() { + echo "Starting Craton docker container..." + docker rm -f craton-api 2>/dev/null || true + docker build --pull -t craton-api:latest . + docker run -t --name craton-api -p 127.0.0.1:7780:7780 -d craton-api:latest + + CRATON_PORT=$(sed -nr "/^\[api\]/ { :l /^port[ ]*=/ { s/.*=[ ]*//; p; q;}; n; b l;}" etc/craton-api-conf.sample) + CRATON_URL=http://$(docker inspect --format '{{ .NetworkSettings.IPAddress }}' craton-api):${CRATON_PORT} + OS_PROJECT_ID=probe + OS_USERNAME=probe + OS_PASSWORD=probe + until craton-get v1/regions 2>/dev/null + do + echo "Waiting for API server"; sleep 1 + done + + eval $(craton-docker-env) + craton-fake-data + + docker logs -f craton-api +}