From 291b547d56fbc4b36b0c844e23a1fd55045130b6 Mon Sep 17 00:00:00 2001 From: Petra Vankova Date: Tue, 13 May 2025 14:05:17 +0200 Subject: [PATCH] static --- apps/docs/content/static/overview.mdx | 135 +++++++++++++++++++++++++- apps/docs/static/llms-full.txt | 108 ++++++++++++++++++++- apps/docs/static/llms-small.txt | 108 ++++++++++++++++++++- 3 files changed, 348 insertions(+), 3 deletions(-) diff --git a/apps/docs/content/static/overview.mdx b/apps/docs/content/static/overview.mdx index 0f533bd7..6c5709f1 100644 --- a/apps/docs/content/static/overview.mdx +++ b/apps/docs/content/static/overview.mdx @@ -174,6 +174,107 @@ In this configuration: - `/blog/post-123.html` will redirect to `/articles/post-123.html` - Any other path will show the content from `/index.html` while preserving the original URL (common for SPAs) +### CORS Configuration + +You can easily enable CORS for your static service by adding a `cors` directive: + +```yaml title="zerops.yaml" +run: + routing: + # Simple case - automatically converted to '*' + cors: "*" + + # Full syntax with proper quoting + cors: "'*' always" +``` + +:::note +The `cors` directive has a special case: if you specify just `"*"`, it's automatically converted to `'*'`. For any other values, you need to include the proper Nginx syntax including quotes. +::: + +### Custom Headers + +For more fine-grained control over HTTP headers, use the `headers` directive: + +```yaml title="zerops.yaml" +run: + routing: + headers: + - for: "/" + values: + # All values need proper quoting since they're inserted directly into Nginx + X-Frame-Options: "'DENY'" + + # Values with internal quotes need proper YAML escaping + Content-Security-Policy: '"default-src ''self''"' +``` + +:::important +Header values are inserted directly into the Nginx configuration **without** additional quotes, which means: + +1. **All values must include their own quotes** (typically single quotes) +2. If you need single quotes inside your header value, you must escape them in YAML (using double single quotes) +3. To include the `always` directive, add it after your quoted value +4. For complex values, you can use YAML's block scalar notation (`>-`) for better readability +::: + +Here are examples for different header scenarios: + +```yaml title="zerops.yaml" +headers: + - for: "/" + values: + # Simple header with proper quoting + X-Frame-Options: "'DENY'" + + # Header with 'always' directive + X-XSS-Protection: "'1; mode=block' always" + + # Header with internal single quotes - need double single quotes for escaping + Content-Security-Policy: '"default-src ''self'' https://cdn.example.com"' + + # Complex header with block scalar notation for better readability + Content-Security-Policy: >- + "default-src 'self' https://cdn.example.com; + script-src 'self' 'unsafe-inline'; + img-src * data:" always +``` + +When this configuration is processed, it translates to the following Nginx directives: + +``` +add_header X-Frame-Options 'DENY'; +add_header X-XSS-Protection '1; mode=block' always; +add_header Content-Security-Policy "default-src 'self' https://cdn.example.com"; +add_header Content-Security-Policy "default-src 'self' https://cdn.example.com; script-src 'self' 'unsafe-inline'; img-src * data:" always; +``` + +:::important Path Handling +When you specify headers for a path that doesn't have an existing location block, the Static service automatically creates a location with the same default behavior as the root path (trying files in order: `$uri`, `$uri.html`, `$uri/index.html`, `/index.html` or returning 404). + +If you add headers for a path that already has a location block, your headers will be merged with the existing configuration. +::: + +### Combining CORS and Custom Headers + +You can use both CORS and custom headers together: + +```yaml title="zerops.yaml" +run: + routing: + cors: "'*' always" + headers: + - for: "/" + values: + X-Frame-Options: "'DENY'" +``` + +The `cors` directive sets default Access-Control headers for all routes, while the `headers` directive allows you to set additional headers for specific paths. + +:::important +If you specify Access-Control headers in the `headers` directive, they will override the ones set by `cors` for that specific path. +::: + ## Prerender Integration The Static service includes built-in support for Prerender.io, making it easy to implement server-side rendering for search engines and social media crawlers. @@ -187,7 +288,7 @@ The Static service includes built-in support for Prerender.io, making it easy to If you're using a custom Prerender host, add it to environment variables in `zerops.yaml`: -```yaml +```yaml title="zerops.yaml" run: envVariables: - PRERENDER_HOST=your.prerender.host @@ -248,6 +349,19 @@ This allows you to graduate to a more customizable setup while maintaining your status: 302 ``` +4. **Security Headers** + Add security headers to protect your application: + ```yaml title="zerops.yaml" + routing: + headers: + - for: "/*" + values: + X-Frame-Options: "'DENY'" + X-Content-Type-Options: "'nosniff'" + # Note the proper quoting for values with single quotes + Content-Security-Policy: '"default-src ''self''"' + ``` + ## Frontend Framework Integration The Static service seamlessly integrates with modern frontend frameworks. It can serve built static files from any framework while maintaining the option to add custom routing and Prerender.io integration if needed. @@ -308,6 +422,8 @@ run: ```yaml title="zerops.yaml" run: routing: + # CORS with proper quoting + cors: "'*' always" redirects: # API requests - from: /api/* @@ -318,4 +434,21 @@ run: - from: /* to: /index.html status: 302 +``` + +### Security-Enhanced Configuration +```yaml title="zerops.yaml" +run: + routing: + headers: + # Custom headers for default location + - for: "/*" + values: + X-Frame-Options: "'DENY' always" + X-Content-Type-Options: "'nosniff' always" + # Note the proper escaping of single quotes + Content-Security-Policy: '"default-src ''self''" always' + redirects: + - from: /* + to: /index.html ``` \ No newline at end of file diff --git a/apps/docs/static/llms-full.txt b/apps/docs/static/llms-full.txt index a28b1898..d0c0bff5 100644 --- a/apps/docs/static/llms-full.txt +++ b/apps/docs/static/llms-full.txt @@ -31112,6 +31112,82 @@ In this configuration: - `/about` will show content from `/about-us` but keep the URL as `/about` - `/blog/post-123.html` will redirect to `/articles/post-123.html` - Any other path will show the content from `/index.html` while preserving the original URL (common for SPAs) +### CORS Configuration +You can easily enable CORS for your static service by adding a `cors` directive: +```yaml title="zerops.yaml" +run: + routing: + # Simple case - automatically converted to '*' + cors: "*" + # Full syntax with proper quoting + cors: "'*' always" +``` +:::note +The `cors` directive has a special case: if you specify just `"*"`, it's automatically converted to `'*'`. For any other values, you need to include the proper Nginx syntax including quotes. +::: +### Custom Headers +For more fine-grained control over HTTP headers, use the `headers` directive: +```yaml title="zerops.yaml" +run: + routing: + headers: + - for: "/" + values: + # All values need proper quoting since they're inserted directly into Nginx + X-Frame-Options: "'DENY'" + # Values with internal quotes need proper YAML escaping + Content-Security-Policy: '"default-src ''self''"' +``` +:::important +Header values are inserted directly into the Nginx configuration **without** additional quotes, which means: +1. **All values must include their own quotes** (typically single quotes) +2. If you need single quotes inside your header value, you must escape them in YAML (using double single quotes) +3. To include the `always` directive, add it after your quoted value +4. For complex values, you can use YAML's block scalar notation (`>-`) for better readability +::: +Here are examples for different header scenarios: +```yaml title="zerops.yaml" +headers: + - for: "/" + values: + # Simple header with proper quoting + X-Frame-Options: "'DENY'" + # Header with 'always' directive + X-XSS-Protection: "'1; mode=block' always" + # Header with internal single quotes - need double single quotes for escaping + Content-Security-Policy: '"default-src ''self'' https://cdn.example.com"' + # Complex header with block scalar notation for better readability + Content-Security-Policy: >- + "default-src 'self' https://cdn.example.com; + script-src 'self' 'unsafe-inline'; + img-src * data:" always +``` +When this configuration is processed, it translates to the following Nginx directives: +``` +add_header X-Frame-Options 'DENY'; +add_header X-XSS-Protection '1; mode=block' always; +add_header Content-Security-Policy "default-src 'self' https://cdn.example.com"; +add_header Content-Security-Policy "default-src 'self' https://cdn.example.com; script-src 'self' 'unsafe-inline'; img-src * data:" always; +``` +:::important Path Handling +When you specify headers for a path that doesn't have an existing location block, the Static service automatically creates a location with the same default behavior as the root path (trying files in order: `$uri`, `$uri.html`, `$uri/index.html`, `/index.html` or returning 404). +If you add headers for a path that already has a location block, your headers will be merged with the existing configuration. +::: +### Combining CORS and Custom Headers +You can use both CORS and custom headers together: +```yaml title="zerops.yaml" +run: + routing: + cors: "'*' always" + headers: + - for: "/" + values: + X-Frame-Options: "'DENY'" +``` +The `cors` directive sets default Access-Control headers for all routes, while the `headers` directive allows you to set additional headers for specific paths. +:::important +If you specify Access-Control headers in the `headers` directive, they will override the ones set by `cors` for that specific path. +::: ## Prerender Integration The Static service includes built-in support for Prerender.io, making it easy to implement server-side rendering for search engines and social media crawlers. ### Basic Prerender Setup @@ -31119,7 +31195,7 @@ The Static service includes built-in support for Prerender.io, making it easy to 2. The service automatically configures necessary rewrites based on user agents ### Custom Prerender Host If you're using a custom Prerender host, add it to environment variables in `zerops.yaml`: -```yaml +```yaml title="zerops.yaml" run: envVariables: - PRERENDER_HOST=your.prerender.host @@ -31169,6 +31245,18 @@ This allows you to graduate to a more customizable setup while maintaining your to: /index.html status: 302 ``` +4. **Security Headers** + Add security headers to protect your application: + ```yaml title="zerops.yaml" + routing: + headers: + - for: "/*" + values: + X-Frame-Options: "'DENY'" + X-Content-Type-Options: "'nosniff'" + # Note the proper quoting for values with single quotes + Content-Security-Policy: '"default-src ''self''"' + ``` ## Frontend Framework Integration The Static service seamlessly integrates with modern frontend frameworks. It can serve built static files from any framework while maintaining the option to add custom routing and Prerender.io integration if needed. ### Example: Analog App Deployment @@ -31218,6 +31306,8 @@ run: ```yaml title="zerops.yaml" run: routing: + # CORS with proper quoting + cors: "'*' always" redirects: # API requests - from: /api/* @@ -31228,6 +31318,22 @@ run: to: /index.html status: 302 ``` +### Security-Enhanced Configuration +```yaml title="zerops.yaml" +run: + routing: + headers: + # Custom headers for default location + - for: "/*" + values: + X-Frame-Options: "'DENY' always" + X-Content-Type-Options: "'nosniff' always" + # Note the proper escaping of single quotes + Content-Security-Policy: '"default-src ''self''" always' + redirects: + - from: /* + to: /index.html +``` ---------------------------------------- diff --git a/apps/docs/static/llms-small.txt b/apps/docs/static/llms-small.txt index 55e4ff4c..6fd46787 100644 --- a/apps/docs/static/llms-small.txt +++ b/apps/docs/static/llms-small.txt @@ -27704,6 +27704,82 @@ In this configuration: - `/about` will show content from `/about-us` but keep the URL as `/about` - `/blog/post-123.html` will redirect to `/articles/post-123.html` - Any other path will show the content from `/index.html` while preserving the original URL (common for SPAs) +### CORS Configuration +You can easily enable CORS for your static service by adding a `cors` directive: +```yaml title="zerops.yaml" +run: + routing: + # Simple case - automatically converted to '*' + cors: "*" + # Full syntax with proper quoting + cors: "'*' always" +``` +:::note +The `cors` directive has a special case: if you specify just `"*"`, it's automatically converted to `'*'`. For any other values, you need to include the proper Nginx syntax including quotes. +::: +### Custom Headers +For more fine-grained control over HTTP headers, use the `headers` directive: +```yaml title="zerops.yaml" +run: + routing: + headers: + - for: "/" + values: + # All values need proper quoting since they're inserted directly into Nginx + X-Frame-Options: "'DENY'" + # Values with internal quotes need proper YAML escaping + Content-Security-Policy: '"default-src ''self''"' +``` +:::important +Header values are inserted directly into the Nginx configuration **without** additional quotes, which means: +1. **All values must include their own quotes** (typically single quotes) +2. If you need single quotes inside your header value, you must escape them in YAML (using double single quotes) +3. To include the `always` directive, add it after your quoted value +4. For complex values, you can use YAML's block scalar notation (`>-`) for better readability +::: +Here are examples for different header scenarios: +```yaml title="zerops.yaml" +headers: + - for: "/" + values: + # Simple header with proper quoting + X-Frame-Options: "'DENY'" + # Header with 'always' directive + X-XSS-Protection: "'1; mode=block' always" + # Header with internal single quotes - need double single quotes for escaping + Content-Security-Policy: '"default-src ''self'' https://cdn.example.com"' + # Complex header with block scalar notation for better readability + Content-Security-Policy: >- + "default-src 'self' https://cdn.example.com; + script-src 'self' 'unsafe-inline'; + img-src * data:" always +``` +When this configuration is processed, it translates to the following Nginx directives: +``` +add_header X-Frame-Options 'DENY'; +add_header X-XSS-Protection '1; mode=block' always; +add_header Content-Security-Policy "default-src 'self' https://cdn.example.com"; +add_header Content-Security-Policy "default-src 'self' https://cdn.example.com; script-src 'self' 'unsafe-inline'; img-src * data:" always; +``` +:::important Path Handling +When you specify headers for a path that doesn't have an existing location block, the Static service automatically creates a location with the same default behavior as the root path (trying files in order: `$uri`, `$uri.html`, `$uri/index.html`, `/index.html` or returning 404). +If you add headers for a path that already has a location block, your headers will be merged with the existing configuration. +::: +### Combining CORS and Custom Headers +You can use both CORS and custom headers together: +```yaml title="zerops.yaml" +run: + routing: + cors: "'*' always" + headers: + - for: "/" + values: + X-Frame-Options: "'DENY'" +``` +The `cors` directive sets default Access-Control headers for all routes, while the `headers` directive allows you to set additional headers for specific paths. +:::important +If you specify Access-Control headers in the `headers` directive, they will override the ones set by `cors` for that specific path. +::: ## Prerender Integration The Static service includes built-in support for Prerender.io, making it easy to implement server-side rendering for search engines and social media crawlers. ### Basic Prerender Setup @@ -27711,7 +27787,7 @@ The Static service includes built-in support for Prerender.io, making it easy to 2. The service automatically configures necessary rewrites based on user agents ### Custom Prerender Host If you're using a custom Prerender host, add it to environment variables in `zerops.yaml`: -```yaml +```yaml title="zerops.yaml" run: envVariables: - PRERENDER_HOST=your.prerender.host @@ -27761,6 +27837,18 @@ This allows you to graduate to a more customizable setup while maintaining your to: /index.html status: 302 ``` +4. **Security Headers** + Add security headers to protect your application: + ```yaml title="zerops.yaml" + routing: + headers: + - for: "/*" + values: + X-Frame-Options: "'DENY'" + X-Content-Type-Options: "'nosniff'" + # Note the proper quoting for values with single quotes + Content-Security-Policy: '"default-src ''self''"' + ``` ## Frontend Framework Integration The Static service seamlessly integrates with modern frontend frameworks. It can serve built static files from any framework while maintaining the option to add custom routing and Prerender.io integration if needed. ### Example: Analog App Deployment @@ -27810,6 +27898,8 @@ run: ```yaml title="zerops.yaml" run: routing: + # CORS with proper quoting + cors: "'*' always" redirects: # API requests - from: /api/* @@ -27820,6 +27910,22 @@ run: to: /index.html status: 302 ``` +### Security-Enhanced Configuration +```yaml title="zerops.yaml" +run: + routing: + headers: + # Custom headers for default location + - for: "/*" + values: + X-Frame-Options: "'DENY' always" + X-Content-Type-Options: "'nosniff' always" + # Note the proper escaping of single quotes + Content-Security-Policy: '"default-src ''self''" always' + redirects: + - from: /* + to: /index.html +``` ----------------------------------------