You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This image can be used as a base image for single page applications. It is itself based on Nginx.
5
+
This container image provides a base for serving Single Page Applications (SPAs), leveraging Nginx as its web server.
6
+
7
+
For a fitting Helm Chart see [chart/README.md](https://github.com/codecentric/single-page-application-server/blob/master/chart/README.md).
5
8
6
9
## Tags
7
10
8
-
The following tags will be updated automatically with the latest nginx base image on a weekly basis:
11
+
The following tags are updated automatically on a weekly basis with the latest Nginx base image:
9
12
10
13
*`latest` (alias for `1-nginx-stable-alpine`)
11
14
*`1` (alias for `1-nginx-stable-alpine`)
@@ -14,54 +17,73 @@ The following tags will be updated automatically with the latest nginx base imag
14
17
*`latest-nginx-mainline-alpine` (alias for `1-nginx-mainline-alpine`)
15
18
*`1-nginx-mainline-alpine`
16
19
17
-
There will also be tags for specific versions.
20
+
Additional tags for specific Nginx versions are also available.
18
21
19
22
## Examples
20
23
21
24
Examples for usage with Angular and React are located in the `examples` directory.
22
25
23
26
## General Features
24
27
25
-
* Any non-existing routes return the root `index.html`
26
-
* Does NOT apply to resource routes with filename extensions such as: `js | css | ico | pdf | flv | jpg | jpeg | png | gif | swf`
27
-
* Configure application dynamically at container startup
28
-
* Configure base element
29
-
* Support environment specific configuration depending on the requested host (port and domain)
30
-
* Hashed resources are cached indefinitely by the browser without revalidating
31
-
* Resource name needs to look like `my-script.3f8a240b.js` or `my-script.3f8a240b.chunk.js`
32
-
* Hash needs to consist of at least 8 characters
33
-
* Applies to resources with filename extensions such as: `js | css | ico | pdf | flv | jpg | jpeg | png | gif | swf`
34
-
* HTTP 2 is enabled by default for HTTPS connections
28
+
-**SPA Routes Handling**: Routes not matching static files will serve `index.html`, with exceptions for resources like `.js`, `.css`, etc.
29
+
-**Dynamic Configuration**: Configure applications at container startup.
30
+
-**Environment-Specific Config**: Customize settings based on port and domain.
31
+
-**Resource Caching**: Hashed resources are cached indefinitely. Resources must include a hash of at least 8 characters.
32
+
-**HTTP/2**: Enabled by default for HTTPS connections.
33
+
-**Helm Chart**: A general [Helm chart](https://github.com/codecentric/single-page-application-server/blob/master/chart/README.md) is available for applications using this image.
35
34
36
35
## Security Features
37
36
38
-
* Restrictive Content Security Policy by default
39
-
* Server API endpoints can be whitelisted automatically
40
-
* Referrer is disabled by default
41
-
* Content Type Sniffing is disabled by default
42
-
* HTTPS is enforced via HSTS by default if enabled
43
-
* HTTPS uses [recommended OWASP protocols and cipher suites](https://cheatsheetseries.owasp.org/cheatsheets/TLS_Cipher_String_Cheat_Sheet.html)
44
-
* Container runs as non-root user
45
-
* Nevertheless the server can still bind to port 80 and 443
46
-
* Serving source map files (*.js.map, *.css.map) is disabled by default
37
+
-**Content Security Policy**: Restrictive by default, with automatic whitelisting for server API endpoints.
38
+
-**Referrer Policy**: Disabled by default to prevent leakage.
39
+
-**Content Type Sniffing**: Disabled by default.
40
+
-**HTTPS**: Enforced via HSTS if enabled; uses [recommended OWASP protocols and cipher suites.](https://cheatsheetseries.owasp.org/cheatsheets/TLS_Cipher_String_Cheat_Sheet.html)
41
+
-**Non-Root User**: The container runs as a non-root user but can bind to ports 80 and 443.
42
+
-**Source Maps**: Disabled by default.
43
+
-**Read-only root filesystem**: [Supported at container runtime](#read-only-root-filesystem-support)
47
44
48
45
## Configuration
49
46
50
47
### App Directory
51
48
52
-
Copy your SPA resources to`/app/`. All resources in this directory will be served by the Nginx server.
49
+
Place your SPA resources in`/app/`. All files in this directory will be served by Nginx.
53
50
54
51
### YAML Configuration
55
52
56
-
The application container is configured via YAML files at startup time.
53
+
Configure the application through YAML files at startup:
57
54
58
-
If you need to configure some default settings for your application image, you can add a default configuration file to `/config/default.yaml`.
55
+
1.**Default Configuration**: Add a default configuration file to `/config/default.yaml`. Usually added during `docker build`.
56
+
2.**Runtime Configuration**: Mount a runtime configuration file at `/config/config.yaml`. This file will override default settings.
59
57
60
-
To configure settings at runtime, you can mount your runtime configuration file at `/config/config.yaml`. Every specified setting in this file will override the default setting.
58
+
#### Example Configuration
61
59
62
-
It is also possible to merge multiple configuration files by specifying the `CONFIG_FILES` environment variable like `CONFIG_FILES="file:///config/config1.yaml|file:///config/config2.yaml"`. The configuration options, specified in the first configuration file in that variable, will have priority over the options in later declared files.
60
+
```yaml
61
+
default:
62
+
spa_config:
63
+
appTitle: "My Application"
64
+
endpoints:
65
+
api: "https://api.example.com"
66
+
```
67
+
68
+
You can also define host-specific configurations:
69
+
70
+
```yaml
71
+
default:
72
+
spa_config:
73
+
appTitle: "My Default Title"
74
+
endpoints:
75
+
api: "https://api.example.com"
76
+
special_host:
77
+
server_names:
78
+
- "special.example.com"
79
+
spa_config:
80
+
appTitle: "My Domain-specific Title"
81
+
```
82
+
83
+
#### Configuration Reference
63
84
64
85
The following configuration shows the default values of this base image for every available setting:
86
+
65
87
```yaml
66
88
default:
67
89
# Specifies to which host names this configuration should apply.
@@ -132,40 +154,20 @@ default:
132
154
style-src: "'self'"
133
155
```
134
156
135
-
Aside to the `default` configuration block, you can also define other blocks, which might define configuration settings for special hosts. The non-default blocks will inherit the configured settings of the default-block if they are not explicitly redeclared.
136
-
137
-
Example:
138
-
```yaml
139
-
default:
140
-
spa_config:
141
-
appTitle: "My Default Application"
142
-
endpoints:
143
-
globalApi: "https://api.example.com"
144
-
special_host:
145
-
server_names:
146
-
- "special.example.com"
147
-
spa_config:
148
-
appTitle: "My Special Application"
149
-
```
150
-
151
-
With this configuration the application would have the app title "My Special Application", when it is accessed via the host `special.example.com`, while the endpoints would stay the same in every instance of the application.
152
-
153
157
## Read-only Root Filesystem Support
154
158
155
-
It is recommended to use a read-only root filesystem when running containers. However, the following directories must remain writable when using this base image:
159
+
For security, use a read-only root filesystem. Ensure the following directories are writable:
156
160
157
-
* `/config/.out`
158
-
* This base image generates files in this directory at startup.
159
-
* `/tmp`
160
-
* Nginx uses this directory to manage cached files and the nginx.pid file. For more information, see [nginxinc/docker-nginx-unprivileged#troubleshooting-tips](https://github.com/nginxinc/docker-nginx-unprivileged/tree/af6e325d35e6833af9cdda8493866b88649e8aaf?tab=readme-ov-file#troubleshooting-tips).
161
+
* `/config/.out`: Used for file generation.
162
+
* `/tmp`: Used by Nginx for cached files and `nginx.pid`.
161
163
162
-
It is possible to mount these directories as writable volumes. When using Kubernetes, one solution is to mount `emptyDir` volumes at these mount points.
164
+
When using Kubernetes, consider mounting these directories as writable volumes with `emptyDir`.
163
165
164
166
## Development
165
167
166
-
Configuration files are dynamically generated via [gomplate templates](https://docs.gomplate.ca/).
167
-
168
-
Tests are written in Java using [Testcontainers](https://www.testcontainers.org/).
0 commit comments