Changes in 931a732: bug4811: more defaults, documented the defaults in the amazon-ec2.md Wiki entry

				configuration/sailing
			
          @@ -163,8 +163,8 @@ reload_httpd() {

           create_basic_httpd_config() {

               FIRST_SERVER=`echo $JAVA_START_INSTANCES | awk '{print $1;}'`

               source $SERVERS_DIR/$FIRST_SERVER/env.sh

          -    echo "Writing macro invocation to ${APACHE_INTERNALS_CONFIG_FILE} to map internal IP $INSTANCE_INTERNAL_IP4 to plain server running $SERVER_PORT..." >/var/log/sailing.err

          -    echo "Use Plain-SSL ${INSTANCE_INTERNAL_IP4} 127.0.0.1 $SERVER_PORT" >>"${APACHE_INTERNALS_CONFIG_FILE}"

          +    echo "Writing macro invocation to ${APACHE_INTERNALS_CONFIG_FILE} to map internal IP $INSTANCE_INTERNAL_IP4 to plain server running $SERVER_PORT..." >>/var/log/sailing.err

          +    echo "Use Plain-SSL ${INSTANCE_INTERNAL_IP4} 127.0.0.1 $SERVER_PORT" >"${APACHE_INTERNALS_CONFIG_FILE}"

               # Append Apache macro invocation for /internal-server-status based on mod_status and INSTANCE_DNS to "${APACHE_INTERNALS_CONFIG_FILE}"

               echo "Appending macro usage for $INSTANCE_DNS/internal-server-status URL for mod_status based Apache monitoring to ${APACHE_INTERNALS_CONFIG_FILE}" >>/var/log/sailing.err

               echo "## SERVER STATUS" >>"${APACHE_INTERNALS_CONFIG_FILE}"

				java/target/env-default-rules.sh
			
          @@ -20,7 +20,7 @@ fi

           # file with a MEMORY assignment which is then used in conjunction with refreshInstance.sh

           # or by setting the MEMORY variable in the EC2 Instance Details section which will be appended

           # at the end of the file.

          -if [ -z $SERVER_NAME ]; then

          +if [ -z $MEMORY ]; then

             MEMORY="6000m"

           fi

          @@ -64,6 +64,9 @@ fi

           if [ -z $EXPEDITION_PORT ]; then

             EXPEDITION_PORT=2010

           fi

          +if [ -z $REPLICATE_MASTER_SERVLET_HOST ]; then

          +  REPLICATE_MASTER_SERVLET_HOST=${SERVER_NAME}.sapsailing.com

          +fi

           if [ -z $REPLICATE_MASTER_SERVLET_PORT ]; then

             REPLICATE_MASTER_SERVLET_PORT=443

           fi

          @@ -82,4 +85,3 @@ fi

           if [ -z $REPLICATE_MASTER_EXCHANGE_NAME ]; then

             REPLICATE_MASTER_EXCHANGE_NAME=${SERVER_NAME}

           fi

          -# **** Overwritten environment variables ****

          \ No newline at end of file

				java/target/env.sh
			
          @@ -124,4 +124,5 @@ ADDITIONAL_JAVA_ARGS="$JAVA_VERSION_SPECIFIC_ARGS $ADDITIONAL_JAVA_ARGS -Dpersis

           #REPLICATE_MASTER_BEARER_TOKEN="..."

           echo ADDITIONAL_JAVA_ARGS=${ADDITIONAL_JAVA_ARGS}

          -ON_AMAZON=`command -v ec2-metadata`

          \ No newline at end of file

          +ON_AMAZON=`command -v ec2-metadata`

          +### End of Standard env.sh ###

				java/target/start
			
          @@ -97,8 +97,8 @@ fi

           if [ -n "$MAIL_SMTP_PORT" ]; then

             echo "mail.smtp.port = $MAIL_SMTP_PORT" >>configuration/mail.properties

           fi

          -if [ -n "$MAIL_AUTH" ]; then

          -  echo "mail.auth = $MAIL_AUTH" >>configuration/mail.properties

          +if [ -n "$MAIL_SMTP_AUTH" ]; then

          +  echo "mail.smtp.auth = $MAIL_SMTP_AUTH" >>configuration/mail.properties

           fi

           if [ -n "$MAIL_SMTP_USER" ]; then

             echo "mail.smtp.user = $MAIL_SMTP_USER" >>configuration/mail.properties

				wiki/info/landscape/amazon-ec2.md
			
          @@ -4,11 +4,15 @@

           ## Quickstart

          -#### Servers

          +Our default region in AWS EC2 is eu-west-1 (Ireland).

          +

          +#### Servers, Hostnames

           - Web Server: ec2-54-229-94-254.eu-west-1.compute.amazonaws.com

           - Database Server: dbserver.internal.sapsailing.com

          -- Database and Queue Server: rabbit.internal.sapsailing.com

          +- RabbitMQ Server: rabbit.internal.sapsailing.com

          +- Standalone MongoDB Server: dbserver.internal.sapsailing.com (archive server winddb on port 10201, all other slow/archived DBs on 10202, hidden replica of "live" replica set on 10203)

          +- MongoDB Servers for "live" replica set: mongo0.internal.sapsailing.com and mongo1.internal.sapsailing.com

           #### Starting an instance

          @@ -24,14 +28,12 @@ You may need to select "All generations" instead of "Current generation" to see 

           Using a release, set the following in the instance's user data, replacing `myspecificevent` by a unique name of the event or series you'll be running on that instance, such as `kielerwoche2014` or similar. Note that when you select to install an environment using the `USE_ENVIRONMENT` variable, any other variable that you specify in the user data, such as the `MONGODB_URI` or `REPLICATION_CHANNEL` properties in the example above, these additional user data properties will override whatever comes from the environment specified by the `USE_ENVIRONMENT` parameter.

          -TODO describe all variable names that may be used here, as well as the defaults that apply if a variable is not specified

          +A typical set-up for a master node could look like this:

           ```

           INSTALL_FROM_RELEASE=(name-of-release)

           USE_ENVIRONMENT=live-master-server

           SERVER_NAME=myspecificevent

          -REPLICATION_CHANNEL=myspecificevent

          -MONGODB_URI="mongodb://mongo0.internal.sapsailing.com,mongo1.internal.sapsailing.com/myspecificevent?replicaSet=live&retryWrites=true&readPreference=nearest"

           # Provide authentication credentials for a user on security-service.sapsailing.com permitted to replicate, either by username/password...

           #REPLICATE_MASTER_USERNAME=(user for replicator login on security-service.sapsailing.com server having SERVER:REPLICATE:&lt;server-name&gt; permission)

           #REPLICATE_MASTER_PASSWORD=(password of the user for replication login on security-service.sapsailing.com)

          @@ -44,6 +46,138 @@ EVENT_ID={some-uuid-of-an-event-you-want-to-feature}

           SERVER_STARTUP_NOTIFY=you@email.com

           ```

          +This will use the default "live" MongoDB replica set with a database named after the `SERVER_NAME` variable, and with an outbound RabbitMQ exchange also named after the `SERVER_NAME` variable, using the default RabbitMQ instance in the landscape for replication purposes, and replicating the SecurityService as well as the SharedSailingData service from the central `security-service.sapsailing.com` instance. Furthermore, a reverse proxy setting for your `EVENT_ID` will be created, using `${SERVER_NAME}.sapsailing.com` as the hostname for the mapping.

          +

          +More variables are available, and some variables---if not set in the environment specified by `USE_ENVIRONMENT` nor in the user data provided when launching the instance---have default values which may be constants or may be computed based on values of other variables, most notably the `SERVER_NAME` variable. Here is the list:

          +

          +* `SERVER_NAME`

          +    used to define the server's name. This is relevant in particular for the user group

          +    created/used for all new server-specific objects such as the `SERVER` object itself. The group's

          +    name is constructed by appending "-server" to the server name. This variable furthermore provides the default value for a few other settings, including the default hostname mapping `${SERVER_NAME}.sapsailing.com` for any series or event specified, the database name in the default `MONGODB_URI`, as well as the default name for the outbound RabbitMQ replication exchange `REPLICATION_CHANNEL`.

          +

          +* `INSTALL_FROM_RELEASE` The user data variable to use to specify the release to install and run on the host. Typical values are `live-master-server` and `live-replica-server`, used to start a master or a replica server, respectively, or `archive-server` for launching an "ARCHIVE" server.

          + 

          +* `MONGODB_URI`

          +    used to specify the MongoDB connection URI; if neither this variable nor `MONGODB_HOST` are specified, a default MongoDB URI will be constructed as `mongodb://mongo0.internal.sapsailing.com,mongo1.internal.sapsailing.com/${SERVER_NAME}?replicaSet=live&retryWrites=true&readPreference=nearest`.

          +

          +* `REPLICATION_CHANNEL`

          +    used to define the name of the RabbitMQ exchange to which this master node

          +    will send its operations bound for its replica nodes. The replica-side counterpart for this is

          +    `REPLICATE_MASTER_EXCHANGE_NAME`. Defaults to `${SERVER_NAME}` if no automatic replication is

          +    requested using the `AUTO_REPLICATE` variable,  otherwise to `${SERVER_NAME}-${INSTANCE_NAME}` which

          +    provides a separate "transitive" replication channel for each replica.

          +

          +* `REPLICATION_HOST`

          +    hostname or IP address of the RabbitMQ node that this master process will use for outbound replication. Defaults to `rabbit.internal.sapsailing.com`.

          +

          +* `REPLICATION_PORT`

          +    the port used by this master process to connect to RabbitMQ for outbound replication. Using 0 (the default)

          +    will use the default port as encoded in the RabbitMQ driver. 

          +

          +* `SERVER_PORT`

          +    The port on which the built-in web server of an application server process can be reached using HTTP. Defaults to 8888.

          +

          +* `TELNET_PORT`

          +    The port on which the OSGi console of a server process can be reached. Defaults to 14888.

          +

          +* `EXPEDITION_PORT`

          +    The port on which the application server will listen for incoming UDP packets, usually then forwarded to the Expedition receiver for wind and other Expedition-based sensor data. Defaults to 2010.

          +    

          +* `SERVER_STARTUP_NOTIFY`

          +    defines one or more comma-separated e-mail addresses to which a notification will

          +    be sent after the server has started successfully.

          +

          +* `USE_ENVIRONMENT`

          +    defines the environment file (stored at `http://releases.sapsailing.com/environments`)

          +    which provides default combinations of variables

          +

          +* `REPLICATE_MASTER_SERVLET_HOST`

          +    the host name or IP address where a replica can reach the master node in order to

          +    request the initial load, register, un-register, and send operations for reverse replication to.

          +    The value is always combined with that of the `REPLICATE_MASTER_SERVLET_PORT` variable which

          +    provides the port for this communication. Defaults to `${SERVER_NAME}.sapsailing.com`, assuming that

          +    this maps to a load balancer that identifies requests bound for the master instance of an

          +    application server replica set and routes them to the master accordingly. Note in this context how with `EVENT_HOSTNAME`

          +    and `SERIES_HOSTNAME` the reverse proxy mappings may be adjusted to use alternative or additional

          +    hostname mappings.

          +

          +* `REPLICATE_MASTER_SERVLET_PORT`

          +    the port number where a replica can reach the master node in order to

          +    request the initial load, register, un-register, and send operations for reverse replication to.

          +    The value is always combined with that of the `REPLICATE_MASTER_SERVLET_HOST` variable which

          +    provides the host name / IP address for this communication. Defaults to 443.

          +

          +* `REPLICATE_MASTER_EXCHANGE_NAME`

          +    the name of the RabbitMQ exchange to which the master sends operations for fan-out

          +    distribution to all replicas, and that therefore a replica has to attach a queue to in order to receive

          +    those operations. Specified on a replica. The master-side counterpart is `REPLICATION_CHANNEL`. Defaults

          +    to `${SERVER_NAME}` which has been the default for the corresponding master based on its `${SERVER_NAME}`

          +    which is assumed to be equal to the `${SERVER_NAME}` setting used to launch this replica.

          +

          +* `REPLICATE_MASTER_QUEUE_HOST`

          +    the RabbitMQ host name that this replica will connect to in order to connect a queue to the

          +    fan-out exchange whose name is provided by the `REPLICATE_MASTER_EXCHANGE_NAME` variable. Used

          +    in conjunction with the `REPLICATE_MASTER_QUEUE_PORT` variable. Defaults to `rabbit.internal.sapsailing.com`.

          +

          +* `REPLICATE_MASTER_QUEUE_PORT`

          +    the RabbitMQ port that this replica will connect to in order to connect a queue to the fan-out

          +    exchange whose name is provided by the `REPLICATE_MASTER_EXCHANGE_NAME` variable. Defaults to 0 which

          +    instructs the driver to use the Rabbit default port (usually 5672) for connecting. Used in conjunction with the

          +    `REPLICATE_MASTER_QUEUE_HOST` variable.

          +

          +* `REPLICATE_ON_START`

          +    specifies the IDs (basically the fully-qualified class names) of those Replicables to

          +    start replicating when the server process starts. The process using this will become a replica for those

          +    replicables specified with this variable, and it will replicate the master node described by

          +    `REPLICATE_MASTER_SERVLET_HOST` and `REPLICATE_MASTER_SERVLET_PORT` and receive the operation

          +    feed through the RabbitMQ exchange configured by `REPLICATE_MASTER_EXCHANGE_NAME`.

          +

          +* `AUTO_REPLICATE`

          +    If this variable has a non-empty value (e.g., "true"), `REPLICATE_ON_START` will default to the set of replicable IDs required by an SAP Sailing Analytics replica instance. Any value provided for `REPLICATE_ON_START` in the environment selected by `USE_ENVIRONMENT` or in the user data provided at instance start-up will take precedence, though.

          +

          +* `REPLICATE_MASTER_BEARER_TOKEN`

          +    used to specify which bearer token to use to authenticate at the master

          +    in case this is to become a replica of some sort, e.g., replicating the SecurityService

          +    and the SharedSailingData service. Use alternatively to `REPLICATE_MASTER_USERNAME/REPLICATE_MASTER_PASSWORD`.

          +

          +* `REPLICATE_MASTER_USERNAME, REPLICATE_MASTER_PASSWORD`

          +    used to specify the user name and password for authenticating at the master

          +    in case this is to become a replica of some sort, e.g., replicating the SecurityService

          +    and the SharedSailingData service. Use alternatively to `REPLICATE_MASTER_BEARER_TOKEN`.

          +

          +* `MEMORY`

          +    Specifies the value to which both, minimum and maximum heap size for the Java VM used to run the application will be set. As of this writing it defaults to "6000m" (6GB). During instance boot-up, a default value is calculated based on the instance's physical memory available, not considering swap space, and appended to the env.sh file. Therefore, auto-installed application processes will never use this "6000m" default. Specifying `MEMORY` in the user data will override the default size computed by the boot script.

          +

          +* `MAIL_FROM`

          +    The address to use in the "From:" header field when the application sends e-mail.

          +

          +* `MAIL_SMTP_HOST`

          +    The SMTP host to use for sending e-mail. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.

          +    

          +* `MAIL_SMTP_PORT`

          +    The SMTP port to use for sending e-mail. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.

          +

          +* `MAIL_SMTP_AUTH`

          +    `true` or `false`; defaults to `false` and tells whether or not to authenticate a user to the SMTP server using the `MAIL_SMTP_USER` and `MAIL_SMTP_PASSWORD` variables. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration and hence defaults this variable to `true`.

          +

          +* `MAIL_SMTP_USER`

          +    Username for SMTP authentication; used if `MAIL_SMTP_AUTH` is `true`. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.

          +

          +* `MAIL_SMTP_PASSWORD`

          +    Password for SMTP authentication; used if `MAIL_SMTP_AUTH` is `true`. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.

          +

          +* `EVENT_ID`...

          +

          +* `SERIES_ID`...

          +

          +* `image-upgrade`

          +    If provided in a line of its own, the `httpd` server on the instance will be stopped, no application server release will be installed, the operating system packages will be updated, the git repository under `/home/sailing/code` will be pulled for the branch that the workspace is checked out on for the image launched (usually `master`) which will update various scripts relevant for the bootstrapping process, all log directories for `httpd` and the application server will be cleared, and by default the instance will then be shut down for a new AMI to be created for it. See also the `no-shutdown` user data option.

          +

          +* `no-shutdown`

          +    If provided in conjunction with the `image-upgrade` option, also on a line of its own, after performing the `image-upgrade` actions the instance will be kept running. This way, you may still log on using SSH and make further adjustments if needed before you create the new image.

          +     

          +TODO describe all variable names that may be used here, as well as the defaults that apply if a variable is not specified

          +

           Have at least a public-facing target group ready. If you want to expose the master to the public (single-instance scenario or master-replica scenario where the master also handles reading client requests) add the master to the public target group.

           If you want to launch one or more replicas, ensure you have a dedicated ``...-master`` target group to which you add your master instance, and a load balancer rule that forwards your replica's requests directed to the master to that ``...-master`` target group, for example, by using a dedicated ``...-master`` hostname rule in your load balancer which then forwards to the ``...-master`` target group.

...	...	@@ -163,8 +163,8 @@ reload_httpd() {
163	163	create_basic_httpd_config() {
164	164	FIRST_SERVER=`echo $JAVA_START_INSTANCES \| awk '{print $1;}'`
165	165	source $SERVERS_DIR/$FIRST_SERVER/env.sh
166		- echo "Writing macro invocation to ${APACHE_INTERNALS_CONFIG_FILE} to map internal IP $INSTANCE_INTERNAL_IP4 to plain server running $SERVER_PORT..." >/var/log/sailing.err
167		- echo "Use Plain-SSL ${INSTANCE_INTERNAL_IP4} 127.0.0.1 $SERVER_PORT" >>"${APACHE_INTERNALS_CONFIG_FILE}"
	166	+ echo "Writing macro invocation to ${APACHE_INTERNALS_CONFIG_FILE} to map internal IP $INSTANCE_INTERNAL_IP4 to plain server running $SERVER_PORT..." >>/var/log/sailing.err
	167	+ echo "Use Plain-SSL ${INSTANCE_INTERNAL_IP4} 127.0.0.1 $SERVER_PORT" >"${APACHE_INTERNALS_CONFIG_FILE}"
168	168	# Append Apache macro invocation for /internal-server-status based on mod_status and INSTANCE_DNS to "${APACHE_INTERNALS_CONFIG_FILE}"
169	169	echo "Appending macro usage for $INSTANCE_DNS/internal-server-status URL for mod_status based Apache monitoring to ${APACHE_INTERNALS_CONFIG_FILE}" >>/var/log/sailing.err
170	170	echo "## SERVER STATUS" >>"${APACHE_INTERNALS_CONFIG_FILE}"

...	...	@@ -20,7 +20,7 @@ fi
20	20	# file with a MEMORY assignment which is then used in conjunction with refreshInstance.sh
21	21	# or by setting the MEMORY variable in the EC2 Instance Details section which will be appended
22	22	# at the end of the file.
23		-if [ -z $SERVER_NAME ]; then
	23	+if [ -z $MEMORY ]; then
24	24	MEMORY="6000m"
25	25	fi
26	26
...	...	@@ -64,6 +64,9 @@ fi
64	64	if [ -z $EXPEDITION_PORT ]; then
65	65	EXPEDITION_PORT=2010
66	66	fi
	67	+if [ -z $REPLICATE_MASTER_SERVLET_HOST ]; then
	68	+ REPLICATE_MASTER_SERVLET_HOST=${SERVER_NAME}.sapsailing.com
	69	+fi
67	70	if [ -z $REPLICATE_MASTER_SERVLET_PORT ]; then
68	71	REPLICATE_MASTER_SERVLET_PORT=443
69	72	fi
...	...	@@ -82,4 +85,3 @@ fi
82	85	if [ -z $REPLICATE_MASTER_EXCHANGE_NAME ]; then
83	86	REPLICATE_MASTER_EXCHANGE_NAME=${SERVER_NAME}
84	87	fi
85		-# ** Overwritten environment variables **
...	...	\ No newline at end of file

...	...	@@ -124,4 +124,5 @@ ADDITIONAL_JAVA_ARGS="$JAVA_VERSION_SPECIFIC_ARGS $ADDITIONAL_JAVA_ARGS -Dpersis
124	124	#REPLICATE_MASTER_BEARER_TOKEN="..."
125	125
126	126	echo ADDITIONAL_JAVA_ARGS=${ADDITIONAL_JAVA_ARGS}
127		-ON_AMAZON=`command -v ec2-metadata`
...	...	\ No newline at end of file
	0	+ON_AMAZON=`command -v ec2-metadata`
	1	+### End of Standard env.sh ###

...	...	@@ -97,8 +97,8 @@ fi
97	97	if [ -n "$MAIL_SMTP_PORT" ]; then
98	98	echo "mail.smtp.port = $MAIL_SMTP_PORT" >>configuration/mail.properties
99	99	fi
100		-if [ -n "$MAIL_AUTH" ]; then
101		- echo "mail.auth = $MAIL_AUTH" >>configuration/mail.properties
	100	+if [ -n "$MAIL_SMTP_AUTH" ]; then
	101	+ echo "mail.smtp.auth = $MAIL_SMTP_AUTH" >>configuration/mail.properties
102	102	fi
103	103	if [ -n "$MAIL_SMTP_USER" ]; then
104	104	echo "mail.smtp.user = $MAIL_SMTP_USER" >>configuration/mail.properties

...	...	@@ -4,11 +4,15 @@
4	4
5	5	## Quickstart
6	6
7		-#### Servers
	7	+Our default region in AWS EC2 is eu-west-1 (Ireland).
	8	+
	9	+#### Servers, Hostnames
8	10
9	11	- Web Server: ec2-54-229-94-254.eu-west-1.compute.amazonaws.com
10	12	- Database Server: dbserver.internal.sapsailing.com
11		-- Database and Queue Server: rabbit.internal.sapsailing.com
	13	+- RabbitMQ Server: rabbit.internal.sapsailing.com
	14	+- Standalone MongoDB Server: dbserver.internal.sapsailing.com (archive server winddb on port 10201, all other slow/archived DBs on 10202, hidden replica of "live" replica set on 10203)
	15	+- MongoDB Servers for "live" replica set: mongo0.internal.sapsailing.com and mongo1.internal.sapsailing.com
12	16
13	17	#### Starting an instance
14	18
...	...	@@ -24,14 +28,12 @@ You may need to select "All generations" instead of "Current generation" to see
24	28
25	29	Using a release, set the following in the instance's user data, replacing `myspecificevent` by a unique name of the event or series you'll be running on that instance, such as `kielerwoche2014` or similar. Note that when you select to install an environment using the `USE_ENVIRONMENT` variable, any other variable that you specify in the user data, such as the `MONGODB_URI` or `REPLICATION_CHANNEL` properties in the example above, these additional user data properties will override whatever comes from the environment specified by the `USE_ENVIRONMENT` parameter.
26	30
27		-TODO describe all variable names that may be used here, as well as the defaults that apply if a variable is not specified
	31	+A typical set-up for a master node could look like this:
28	32
29	33	```
30	34	INSTALL_FROM_RELEASE=(name-of-release)
31	35	USE_ENVIRONMENT=live-master-server
32	36	SERVER_NAME=myspecificevent
33		-REPLICATION_CHANNEL=myspecificevent
34		-MONGODB_URI="mongodb://mongo0.internal.sapsailing.com,mongo1.internal.sapsailing.com/myspecificevent?replicaSet=live&retryWrites=true&readPreference=nearest"
35	37	# Provide authentication credentials for a user on security-service.sapsailing.com permitted to replicate, either by username/password...
36	38	#REPLICATE_MASTER_USERNAME=(user for replicator login on security-service.sapsailing.com server having SERVER:REPLICATE:<server-name> permission)
37	39	#REPLICATE_MASTER_PASSWORD=(password of the user for replication login on security-service.sapsailing.com)
...	...	@@ -44,6 +46,138 @@ EVENT_ID={some-uuid-of-an-event-you-want-to-feature}
44	46	SERVER_STARTUP_NOTIFY=you@email.com
45	47	```
46	48
	49	+This will use the default "live" MongoDB replica set with a database named after the `SERVER_NAME` variable, and with an outbound RabbitMQ exchange also named after the `SERVER_NAME` variable, using the default RabbitMQ instance in the landscape for replication purposes, and replicating the SecurityService as well as the SharedSailingData service from the central `security-service.sapsailing.com` instance. Furthermore, a reverse proxy setting for your `EVENT_ID` will be created, using `${SERVER_NAME}.sapsailing.com` as the hostname for the mapping.
	50	+
	51	+More variables are available, and some variables---if not set in the environment specified by `USE_ENVIRONMENT` nor in the user data provided when launching the instance---have default values which may be constants or may be computed based on values of other variables, most notably the `SERVER_NAME` variable. Here is the list:
	52	+
	53	+* `SERVER_NAME`
	54	+ used to define the server's name. This is relevant in particular for the user group
	55	+ created/used for all new server-specific objects such as the `SERVER` object itself. The group's
	56	+ name is constructed by appending "-server" to the server name. This variable furthermore provides the default value for a few other settings, including the default hostname mapping `${SERVER_NAME}.sapsailing.com` for any series or event specified, the database name in the default `MONGODB_URI`, as well as the default name for the outbound RabbitMQ replication exchange `REPLICATION_CHANNEL`.
	57	+
	58	+* `INSTALL_FROM_RELEASE` The user data variable to use to specify the release to install and run on the host. Typical values are `live-master-server` and `live-replica-server`, used to start a master or a replica server, respectively, or `archive-server` for launching an "ARCHIVE" server.
	59	+
	60	+* `MONGODB_URI`
	61	+ used to specify the MongoDB connection URI; if neither this variable nor `MONGODB_HOST` are specified, a default MongoDB URI will be constructed as `mongodb://mongo0.internal.sapsailing.com,mongo1.internal.sapsailing.com/${SERVER_NAME}?replicaSet=live&retryWrites=true&readPreference=nearest`.
	62	+
	63	+* `REPLICATION_CHANNEL`
	64	+ used to define the name of the RabbitMQ exchange to which this master node
	65	+ will send its operations bound for its replica nodes. The replica-side counterpart for this is
	66	+ `REPLICATE_MASTER_EXCHANGE_NAME`. Defaults to `${SERVER_NAME}` if no automatic replication is
	67	+ requested using the `AUTO_REPLICATE` variable, otherwise to `${SERVER_NAME}-${INSTANCE_NAME}` which
	68	+ provides a separate "transitive" replication channel for each replica.
	69	+
	70	+* `REPLICATION_HOST`
	71	+ hostname or IP address of the RabbitMQ node that this master process will use for outbound replication. Defaults to `rabbit.internal.sapsailing.com`.
	72	+
	73	+* `REPLICATION_PORT`
	74	+ the port used by this master process to connect to RabbitMQ for outbound replication. Using 0 (the default)
	75	+ will use the default port as encoded in the RabbitMQ driver.
	76	+
	77	+* `SERVER_PORT`
	78	+ The port on which the built-in web server of an application server process can be reached using HTTP. Defaults to 8888.
	79	+
	80	+* `TELNET_PORT`
	81	+ The port on which the OSGi console of a server process can be reached. Defaults to 14888.
	82	+
	83	+* `EXPEDITION_PORT`
	84	+ The port on which the application server will listen for incoming UDP packets, usually then forwarded to the Expedition receiver for wind and other Expedition-based sensor data. Defaults to 2010.
	85	+
	86	+* `SERVER_STARTUP_NOTIFY`
	87	+ defines one or more comma-separated e-mail addresses to which a notification will
	88	+ be sent after the server has started successfully.
	89	+
	90	+* `USE_ENVIRONMENT`
	91	+ defines the environment file (stored at `http://releases.sapsailing.com/environments`)
	92	+ which provides default combinations of variables
	93	+
	94	+* `REPLICATE_MASTER_SERVLET_HOST`
	95	+ the host name or IP address where a replica can reach the master node in order to
	96	+ request the initial load, register, un-register, and send operations for reverse replication to.
	97	+ The value is always combined with that of the `REPLICATE_MASTER_SERVLET_PORT` variable which
	98	+ provides the port for this communication. Defaults to `${SERVER_NAME}.sapsailing.com`, assuming that
	99	+ this maps to a load balancer that identifies requests bound for the master instance of an
	100	+ application server replica set and routes them to the master accordingly. Note in this context how with `EVENT_HOSTNAME`
	101	+ and `SERIES_HOSTNAME` the reverse proxy mappings may be adjusted to use alternative or additional
	102	+ hostname mappings.
	103	+
	104	+* `REPLICATE_MASTER_SERVLET_PORT`
	105	+ the port number where a replica can reach the master node in order to
	106	+ request the initial load, register, un-register, and send operations for reverse replication to.
	107	+ The value is always combined with that of the `REPLICATE_MASTER_SERVLET_HOST` variable which
	108	+ provides the host name / IP address for this communication. Defaults to 443.
	109	+
	110	+* `REPLICATE_MASTER_EXCHANGE_NAME`
	111	+ the name of the RabbitMQ exchange to which the master sends operations for fan-out
	112	+ distribution to all replicas, and that therefore a replica has to attach a queue to in order to receive
	113	+ those operations. Specified on a replica. The master-side counterpart is `REPLICATION_CHANNEL`. Defaults
	114	+ to `${SERVER_NAME}` which has been the default for the corresponding master based on its `${SERVER_NAME}`
	115	+ which is assumed to be equal to the `${SERVER_NAME}` setting used to launch this replica.
	116	+
	117	+* `REPLICATE_MASTER_QUEUE_HOST`
	118	+ the RabbitMQ host name that this replica will connect to in order to connect a queue to the
	119	+ fan-out exchange whose name is provided by the `REPLICATE_MASTER_EXCHANGE_NAME` variable. Used
	120	+ in conjunction with the `REPLICATE_MASTER_QUEUE_PORT` variable. Defaults to `rabbit.internal.sapsailing.com`.
	121	+
	122	+* `REPLICATE_MASTER_QUEUE_PORT`
	123	+ the RabbitMQ port that this replica will connect to in order to connect a queue to the fan-out
	124	+ exchange whose name is provided by the `REPLICATE_MASTER_EXCHANGE_NAME` variable. Defaults to 0 which
	125	+ instructs the driver to use the Rabbit default port (usually 5672) for connecting. Used in conjunction with the
	126	+ `REPLICATE_MASTER_QUEUE_HOST` variable.
	127	+
	128	+* `REPLICATE_ON_START`
	129	+ specifies the IDs (basically the fully-qualified class names) of those Replicables to
	130	+ start replicating when the server process starts. The process using this will become a replica for those
	131	+ replicables specified with this variable, and it will replicate the master node described by
	132	+ `REPLICATE_MASTER_SERVLET_HOST` and `REPLICATE_MASTER_SERVLET_PORT` and receive the operation
	133	+ feed through the RabbitMQ exchange configured by `REPLICATE_MASTER_EXCHANGE_NAME`.
	134	+
	135	+* `AUTO_REPLICATE`
	136	+ If this variable has a non-empty value (e.g., "true"), `REPLICATE_ON_START` will default to the set of replicable IDs required by an SAP Sailing Analytics replica instance. Any value provided for `REPLICATE_ON_START` in the environment selected by `USE_ENVIRONMENT` or in the user data provided at instance start-up will take precedence, though.
	137	+
	138	+* `REPLICATE_MASTER_BEARER_TOKEN`
	139	+ used to specify which bearer token to use to authenticate at the master
	140	+ in case this is to become a replica of some sort, e.g., replicating the SecurityService
	141	+ and the SharedSailingData service. Use alternatively to `REPLICATE_MASTER_USERNAME/REPLICATE_MASTER_PASSWORD`.
	142	+
	143	+* `REPLICATE_MASTER_USERNAME, REPLICATE_MASTER_PASSWORD`
	144	+ used to specify the user name and password for authenticating at the master
	145	+ in case this is to become a replica of some sort, e.g., replicating the SecurityService
	146	+ and the SharedSailingData service. Use alternatively to `REPLICATE_MASTER_BEARER_TOKEN`.
	147	+
	148	+* `MEMORY`
	149	+ Specifies the value to which both, minimum and maximum heap size for the Java VM used to run the application will be set. As of this writing it defaults to "6000m" (6GB). During instance boot-up, a default value is calculated based on the instance's physical memory available, not considering swap space, and appended to the env.sh file. Therefore, auto-installed application processes will never use this "6000m" default. Specifying `MEMORY` in the user data will override the default size computed by the boot script.
	150	+
	151	+* `MAIL_FROM`
	152	+ The address to use in the "From:" header field when the application sends e-mail.
	153	+
	154	+* `MAIL_SMTP_HOST`
	155	+ The SMTP host to use for sending e-mail. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.
	156	+
	157	+* `MAIL_SMTP_PORT`
	158	+ The SMTP port to use for sending e-mail. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.
	159	+
	160	+* `MAIL_SMTP_AUTH`
	161	+ `true` or `false`; defaults to `false` and tells whether or not to authenticate a user to the SMTP server using the `MAIL_SMTP_USER` and `MAIL_SMTP_PASSWORD` variables. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration and hence defaults this variable to `true`.
	162	+
	163	+* `MAIL_SMTP_USER`
	164	+ Username for SMTP authentication; used if `MAIL_SMTP_AUTH` is `true`. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.
	165	+
	166	+* `MAIL_SMTP_PASSWORD`
	167	+ Password for SMTP authentication; used if `MAIL_SMTP_AUTH` is `true`. The standard image has a pre-defined file under `/home/sailing/servers/server/configuration/mail.properties` which contains credentials and configuration for our standard Amazon Simple Email Service (AWS SES) configuration.
	168	+
	169	+* `EVENT_ID`...
	170	+
	171	+* `SERIES_ID`...
	172	+
	173	+* `image-upgrade`
	174	+ If provided in a line of its own, the `httpd` server on the instance will be stopped, no application server release will be installed, the operating system packages will be updated, the git repository under `/home/sailing/code` will be pulled for the branch that the workspace is checked out on for the image launched (usually `master`) which will update various scripts relevant for the bootstrapping process, all log directories for `httpd` and the application server will be cleared, and by default the instance will then be shut down for a new AMI to be created for it. See also the `no-shutdown` user data option.
	175	+
	176	+* `no-shutdown`
	177	+ If provided in conjunction with the `image-upgrade` option, also on a line of its own, after performing the `image-upgrade` actions the instance will be kept running. This way, you may still log on using SSH and make further adjustments if needed before you create the new image.
	178	+
	179	+TODO describe all variable names that may be used here, as well as the defaults that apply if a variable is not specified
	180	+
47	181	Have at least a public-facing target group ready. If you want to expose the master to the public (single-instance scenario or master-replica scenario where the master also handles reading client requests) add the master to the public target group.
48	182
49	183	If you want to launch one or more replicas, ensure you have a dedicated ``...-master`` target group to which you add your master instance, and a load balancer rule that forwards your replica's requests directed to the master to that ``...-master`` target group, for example, by using a dedicated ``...-master`` hostname rule in your load balancer which then forwards to the ``...-master`` target group.