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