Skip to content

static #256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 13, 2025
Merged

static #256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 134 additions & 1 deletion apps/docs/content/static/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -308,6 +422,8 @@ run:
```yaml title="zerops.yaml"
run:
routing:
# CORS with proper quoting
cors: "'*' always"
redirects:
# API requests
- from: /api/*
Expand All @@ -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
```
108 changes: 107 additions & 1 deletion apps/docs/static/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31112,14 +31112,90 @@ 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
1. Set the `PRERENDER_TOKEN` secret variable with your Prerender.io token
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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -31218,6 +31306,8 @@ run:
```yaml title="zerops.yaml"
run:
routing:
# CORS with proper quoting
cors: "'*' always"
redirects:
# API requests
- from: /api/*
Expand All @@ -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
```

----------------------------------------

Expand Down
Loading