github.com/rpdict/ponzu@v0.10.1-0.20190226054626-477f29d6bf5e/docs/src/System-Configuration/Settings.md (about)

     1  title: Configuring Your Ponzu System Settings
     2  
     3  Ponzu has several options which can be configured at run-time. To view these
     4  configuration settings, visit the `/admin/configure` page of your Ponzu CMS.
     5  
     6  ---
     7  
     8  #### Site Name
     9  The Site Name setting changes the displayed name on your admin dashboard. This is
    10  visible publicly on the `/admin/login` page.
    11  
    12  ---
    13  
    14  #### Domain Name
    15  Internally, Ponzu needs to know where its canonical HTTP access origin is, and
    16  requires you to add the qualified domain name you are using. In development, use 
    17  `localhost` or some other name mapped to the loopback address (`127.0.0.1`).
    18  
    19  Once you have deployed your Ponzu server to a remote host and pointed a public 
    20  domain at it, you need to change the Domain Name setting to match. This is 
    21  especially important when fetching TLS (SSL) certificates from [Let's Encrypt](https://letsencrypt.org)
    22  - since the process requires an active, verifiable domain. To set up your server
    23  with TLS over HTTPS connections, follow these steps:
    24  
    25  1. Set your Domain Name in the system configuration
    26  2. Set the Administrator Email to register with Let's Encrypt
    27  2. Stop your Ponzu server
    28  3. Run your Ponzu server with the `--https` flag e.g. `$ ponzu run --https`
    29  4. Visit your CMS admin with `https://` prepended to your URL
    30  
    31  !!! success "Verifying HTTPS / TLS Connections"
    32      If successful, your APIs and CMS will be accessible via HTTPS, and you will
    33      see a green indicator near the URL bar of most browsers. This also enables 
    34      your server to use the HTTP/2 protocol.
    35  
    36  ##### Development Environment
    37  
    38  You can test HTTPS & HTTP/2 connections in your development environment on `localhost`,
    39  by running Ponzu with the `--devhttps` flag e.g. `$ ponzu --devhttps run` 
    40  
    41  If you're greeted with a warning from the browser saying the connection is not
    42  secure, follow the steps outlined in the CLI message, or here:
    43  ```
    44  If your browser rejects HTTPS requests, try allowing insecure connections on localhost.
    45  on Chrome, visit chrome://flags/#allow-insecure-localhost
    46  ```
    47  
    48  ---
    49  
    50  #### Administrator Email
    51  The Administrator Email is the contact email for the person who is the main admin
    52  of your Ponzu CMS. This can be changed at any point, but once a Let's Encrypt
    53  certificate has been fetched using an Administrator Email, it will remain the 
    54  contact until a new certificate is requested. 
    55  
    56  ---
    57  
    58  #### Client Secret
    59  The Client Secret is a secure value used by the server to sign tokens and authenticate requests.
    60  **Do not share this** value with any untrusted party.
    61  
    62  !!! danger "Security and the Client Secret"
    63      HTTP requests with a valid token, signed with the Client Secret, can take any
    64      action an Admin can within the CMS. Be cautious of this when sharing account
    65      logins or details with anyone.
    66  
    67  ---
    68  
    69  #### Etag Header
    70  The Etag Header value is automatically created when content is changed and serves
    71  as a caching validation mechanism.
    72  
    73  ---
    74  
    75  #### CORS
    76  CORS, or "Cross-Origin Resource Sharing" is a security setting which defines how
    77  resources (or URLs) can be accessed from outside clients / domains. By default, 
    78  Ponzu HTTP APIs can be accessed from any origin, meaning a script from an unknown
    79  website could fetch data. 
    80  
    81  By disabling CORS, you limit API requests to only the Domain Name you set.
    82  
    83  ---
    84  
    85  #### GZIP
    86  GZIP is a popular codec which when applied to most HTTP responses, decreases data
    87  transmission size and response times. The GZIP setting on Ponzu has a minor 
    88  side-effect of using more CPU, so you can disable it if you notice your system 
    89  is CPU-constrained. However, traffic levels would need to be extremely demanding
    90  for this to be noticeable.
    91  
    92  ---
    93  
    94  #### HTTP Cache
    95  The HTTP Cache configuration allows a system to disable the default HTTP cache,
    96  which saves the server from repeating API queries and sending responses -- it's
    97  generally advised to keep this enabled unless you have _frequently_ changing data.
    98  
    99  The `Max-Age` value setting overrides the default 2592000-second (30 day) cache
   100  `max-age` duration set in API response headers. The `0` value is an alias to 
   101  `2592000`, so check the `Disable HTTP Cache` box if you don't want any caching.
   102  
   103  
   104  ---
   105  
   106  #### Invalidate Cache
   107  If this box is checked and then the configuration is saved, the server will 
   108  re-generate an Etag to send in responses. By doing so, the cache becomes invalidated
   109  and reset so new content or assets will be included in previously cached responses.
   110  
   111  The cache is invalidated when content changes, so this is typically not a widely 
   112  used setting.
   113  
   114  ---
   115  
   116  #### Database Backup Credentials
   117  In order to enable HTTP backups of the components that make up your system, you
   118  will need to add an HTTP Basic Auth user and password pair. When used to 
   119  [run backups](/Running-Backups/Backups), the `user:password` pair tells your server
   120  that the backup request is made from a trusted party. 
   121  
   122  !!! danger "Backup Access with Credentials"
   123      This `user:password` pair should not be shared outside of your organization as 
   124      it allows full database downloads and archives of your system's uploads.