add more docs to activation.json

config/activation.json

@@ -1,10 +1,33 @@
+// ----------------------
+// Bubble Activation JSON
+// ----------------------
+//
+// Do not edit this file directly. Copy this file somewhere else and edit the copy.
+//
+// When you are happy with your edits, activate a blank bubble using:
+//
+//     ./bin/bactivate /path/to/your/activation.json
+//
+// NOTE: In this file, if you see '//' it means that it and everything after it on that line is a comment.
+// Normally comments are not valid JSON, but when you run `bactivate` the Bubble toolchain strips out
+// the comments before sending the request to the Bubble server.
+//
+
 {
-  // name, password and description of the initial admin user
-  "name": "root",    // do not change this, the initial admin user must be named root
+  ///////////////////////
+  // Initial Admin
+  ///////////////////////
+
+  // email, password and description of the initial admin user
+  "name": "root@local.local", // change this to an email address only you have access to
   "password": "REPLACE WITH YOUR ROOT PASSWORD",
   "description": "root user",
 
   "cloudConfigs" : {
+    ///////////////////////
+    // DNS
+    ///////////////////////
+
     // You must configure at least one of these DNS services
     // Comment the other one out if you're not going to use it
     "Route53Dns" : {
@@ -13,6 +36,7 @@
         "AWS_SECRET_KEY": "your_aws_secret_key"
       }
     },
+
     "GoDaddyDns" : {
       "credentials" : {
         "GODADDY_API_KEY": "your_godaddy_api_key",
@@ -20,14 +44,20 @@
       }
     },
 
+    ///////////////////////
+    // Compute
+    ///////////////////////
+
     // You must configure at least one of these Compute services
     // Comment the other one out if you're not going to use it
     "VultrCompute": {
       "credentials": {"API-Key": "your_vultr_api_key"}
     },
+
     "DigitalOceanCompute": {
       "credentials": {"apiKey": "your_digitalocean_api_key"}
     },
+
     "AmazonEC2Driver" : {
       "config": {
         // region must be a valid value from the Regions enum: https://github.com/aws/aws-sdk-java/blob/master/aws-java-sdk-core/src/main/java/com/amazonaws/regions/Regions.java
@@ -39,6 +69,10 @@
       }
     },
 
+    ///////////////////////
+    // Storage
+    ///////////////////////
+
     // You must configure the AWS S3 Storage service in order to launch new Bubbles
     "S3Storage" : {
       "config": {
@@ -54,12 +88,14 @@
       }
     },
 
+    ///////////////////////
+    // Email
+    ///////////////////////
+
     // You must configure an email service, it is required to send emails
-    // Comment out the email clouds that you don't use
+    // Comment out the other ones out if you're not going to use them
     "SmtpEmail": {
-      "config": {
-        "tlsEnabled": true
-      },
+      "config": { "tlsEnabled": true },
       "credentials": {
         "user": "your_smtp_username",
         "password": "your_smtp_password",
@@ -83,10 +119,19 @@
       }
     },
 
+    ///////////////////////
+    // TOTP Auth
+    ///////////////////////
+
     // Required for TOTP-based authentication. Nothing to configure, just leave this as-is
     "TOTPAuthenticator": {},
 
+    ///////////////////////
+    // SMS
+    ///////////////////////
+
     // Required for sending SMS messages. Currently only Twilio is supported
+    // Comment this out if you're not going to use it
     "TwilioSms": {
       "credentials": {
         "accountSID": "your_twilio_account_SID",
@@ -96,7 +141,12 @@
       }
     },
 
-    // Required for locale and "nearest compute region" auto-detection. Currently only MaxMind is supported.
+    ///////////////////////
+    // GeoLocation
+    ///////////////////////
+
+    // Required for locale and "nearest compute region" auto-detection. Currently only MaxMind is supported
+    // Comment this out if you're not going to use it
     "MaxMind": {
       "config": {
         // these values work for the free GeoLite database, but you still have to specify an apiKey
@@ -106,20 +156,86 @@
       "credentials": {"apiKey": "your_maxmind_api_key"}
     },
 
-    // Required for "nearest compute region" auto-detection. Currently only Google GeoCoder is supported.
+    ///////////////////////
+    // GeoCode
+    ///////////////////////
+
+    // Required for "nearest compute region" auto-detection. Currently only Google GeoCoder is supported
+    // Comment this out if you're not going to use it
     "GoogleGeoCoder": {
       "credentials": {"apiKey": "your_google_api_key"}
     },
 
-    // Required for timezone auto-detection. Currently only Google GeoTime is supported.
+    ///////////////////////
+    // GeoTime
+    ///////////////////////
+
+    // Required for timezone auto-detection. Currently only Google GeoTime is supported
+    // Comment this out if you're not going to use it
     "GoogleGeoTime": {
       "credentials": {"apiKey": "your_google_api_key"}
     }
   },
 
+  ///////////////////////
+  // Initial Domain
+  ///////////////////////
+
   // initial domain that new Bubbles will be launched within
   "domain": {
     "publicDns": "Route53Dns or GoDaddyDns",  // name of a DNS provider configured above
     "name": "example.com"  // a domain name that you own, that is managed by the DNS provider named in `publicDns`
-  }
+  },
+
+  ///////////////////////
+  // Expert Settings
+  ///////////////////////
+
+  // You can safely chop off everything from here down from your copy.
+
+  // The settings below rarely be changed, omitting them is the same as not changing them
+  // and you really shouldn't change them unless you know what you're doing.
+
+  // -----------
+  // skipTests
+  // -----------
+  //
+  // Most of the cloud services you add above have "self-test" features in their Bubble driver.
+  // Normally, Bubble will test each cloud driver to ensure that it is working properly before
+  // allowing activation to proceed.
+  //
+  // The driver test can detect a lot of configuration problems, invalid API keys, and so on.
+  // It's a good idea to leave the tests enabled.
+  //
+  // If, however, this is not the first time you've run with the exact same JSON file and you KNOW that
+  // all the clouds/credentials/configs are correct, because they've passed tests before, then setting
+  // this to true does save a little bit of time during activation.
+  //
+  // NOTE: DO NOT SET THIS TO true UNLESS YOU *KNOW* ALL YOUR DRIVERS ARE OK
+  //
+  // If the activation.json file has no `skipTests` property, then tests will be enabled
+  //
+  "skipTests": false,   // set this to true to skip cloud driver tests
+
+  // -----------
+  // skipPacker
+  // -----------
+  //
+  // Bubble needs to ensure that packer images are available on any cloud compute service where you could
+  // launch a new Bubble. The easiest way to ensure this happens is to check for packer images immediately after
+  // activation. This is the default behavior.
+  //
+  // It's a good idea to do this, because if the images don't exist, then Bubble won't check again until you're
+  // about to launch your Bubble -- and then you take the 20-minute delay of building the image.
+  //
+  // If, however, you KNOW that the images exist, or you explicitly want to create them later using the
+  // `pack_bubble` command, you can skip the packer check during activation by setting this to true
+  //
+  // NOTE: DO NOT SET THIS TO true UNLESS YOU *KNOW* THE PACKER IMAGES ARE VALID FOR YOUR CLOUD PROVIDER
+  //
+  // If the activation.json file has no `skipPacker` property, then packer images will be created during activation,
+  // if not already present.
+  //
+  "skipPacker": false
+
 }