https://github.com/gowebprod/k8s-static-server
https://github.com/gowebprod/k8s-static-server
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/gowebprod/k8s-static-server
- Owner: GoWebProd
- License: mit
- Created: 2025-01-12T18:18:28.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-10-30T18:15:34.000Z (8 months ago)
- Last Synced: 2025-12-28T06:14:25.298Z (6 months ago)
- Language: Go
- Size: 76.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# k8s-static-server
## Installation
```bash
git clone https://github.com/GoWebProd/k8s-static-server.git
helm install -n static --create-namespace static-server ./k8s-static-server
```
## Creating static server
```yaml
apiVersion: static-server.webprod.io/v1
kind: StaticRepo
metadata:
name: roubi
namespace: static
spec:
hostname: roubi.fake.com
git:
repo: SOME_REPO
commit: SOME_COMMIT
---
apiVersion: static-server.webprod.io/v1
kind: StaticRepo
metadata:
name: voyah
namespace: static
spec:
hostname: voyah.fake.com
cmd:
image: alpine/git:latest
command:
- /bin/sh
- -c
- echo $DATA_DIR && mkdir -p $DATA_DIR/cunbaemul/otan/ && echo "999999999" > $DATA_DIR/cunbaemul/otan/activate3
---
apiVersion: static-server.webprod.io/v1
kind: StaticRepo
metadata:
name: wiki
namespace: static
spec:
hostname: docmost.fake.com
imageDir:
image: docmost/docmost:0.6.2
path: /app/apps/client/dist/
```
## Server-Side Rendering (SSR)
The static-server supports Server-Side Rendering with Node.js for dynamic content. When SSR is enabled, a Node.js sidecar container is automatically added to handle SSR requests while nginx serves static assets.
### Prerequisites
- Your SSR application should be pre-built and include a `server.js` (or custom entrypoint) that exports a request handler
- The handler should be compatible with Express.js middleware signature: `(req, res, next) => {}`
- All dependencies should be bundled with your application code
### Example: Next.js with SSR
```yaml
apiVersion: static-server.webprod.io/v1
kind: StaticRepo
metadata:
name: nextjs-app
namespace: static
spec:
hostname: app.example.com
imageDir:
image: registry.example.com/my-nextjs-app:v1.0.0
path: /app/.next/standalone
imagePullSecrets:
- name: regcred
ssr:
enabled: true
entryPoint: server.js # Optional, defaults to "server.js"
envVars:
- name: PORT
value: "3000"
- name: NEXT_PUBLIC_API_URL
value: "https://api.example.com"
```
### How it works
1. **Routing**: nginx tries to serve static files first, then falls back to the Node.js SSR server
2. **Static assets** (`.js`, `.css`, images) are always served by nginx for performance
3. **API routes** (e.g., `/api/*`, `/_next/*`) are proxied directly to Node.js (never cached)
4. **Dynamic pages** that don't have static files are handled by SSR
### SSR Response Caching
SSR responses are cached by nginx to reduce Node.js load and improve performance:
- **Cache size**: 100MB by default (configurable via `ssr.cache.size`)
- **Cache TTL**: 60 seconds for successful responses (configurable via `ssr.cache.ttl`)
- **Cache key**: `$scheme$host$request_uri` (varies by protocol, hostname, and path)
**Cache is bypassed for:**
- Requests with `Authorization` header (authenticated users)
- Non-GET/HEAD requests (POST, PUT, DELETE, PATCH)
- Requests with `X-No-Cache` header
**Debugging cache:**
Check the `X-Cache-Status` response header:
- `HIT` - served from cache
- `MISS` - not in cache, proxied to Node.js
- `BYPASS` - cache bypassed due to conditions
- `EXPIRED` - cache expired, updating
**Disable caching:**
```yaml
# values.yaml
ssr:
cache:
enabled: false
```
### SSR Server Requirements
Your `server.js` should export a handler function:
```javascript
// CommonJS
module.exports = function(req, res, next) {
// Your SSR logic here
res.send('...');
};
// or ES modules
export default function(req, res, next) {
// Your SSR logic here
};
// or Next.js standalone server
const NextServer = require('next/dist/server/next-server').default;
module.exports = function(req, res) {
const server = new NextServer({...});
return server.getRequestHandler()(req, res);
};
```
### Multiple SSR Sites
Multiple StaticRepo resources can have SSR enabled. A single Node.js process handles all SSR-enabled sites, routing requests based on the `Host` header.
See [examples/staticrepo-with-ssr.yaml](examples/staticrepo-with-ssr.yaml) for more examples.
## Creating ingress
```yaml
kind: Service
apiVersion: v1
metadata:
name: static-server
namespace: application
spec:
type: ExternalName
externalName: static-server.static.svc.cluster.local
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: static-server
namespace: application
spec:
rules:
- host: roubi.fake.com
http: &httpTemplate
paths:
- pathType: Prefix
path: /
backend:
service:
name: static-server
port:
number: 80
- host: voyah.fake.com
http: *httpTemplate
- host: docmost.fake.com
http: *httpTemplate
tls:
- hosts:
- roubi.fake.com
- voyah.fake.com
- docmost.fake.com
secretName: static-server-cert
```