A static site can start as a source project that needs compilation or as a folder of HTML, CSS and JavaScript ready to publish. Impreza supports both paths on your VPS, served by unprivileged Nginx. Choose the recipe that matches what you have instead of adding an unnecessary build step.
Choose source build or ready-made files
| Recipe | Input | Default routing |
|---|---|---|
| node_npm_static | An npm project with a build script and matching lockfile | SPA fallback on |
| static_files | A selected folder with a regular index.html and ready-made assets | SPA fallback off |
Both serve static files. They do not run a server-side Node app after publication. Use a Node server recipe if the application needs a persistent Node process.
Publish a folder without running npm
Choose static_files in the custom-app form. The selected project_dir is the website root, so put a regular index.html there and keep the asset paths relative to that published layout. No package manager or build command runs.
The recipe refuses symlinks and excludes hidden files and folders. The site is limited to 10,000 files and 256 MiB. There is no build-secret or separate output-directory option: publish the folder that already contains the finished site. Inspect its contents first, since everything served is public to its intended visitors.
With static_spa left false, an unknown path returns 404. Enable it only if a browser-side router should handle those paths through index.html. A documentation site or a set of HTML pages usually needs real missing-page responses.
Build an npm project before serving it
Choose node_npm_static for a compatible React, Vue, Astro or other npm build. The project needs its package definition, lockfile and production build script. Set static_output_dir to the output directory, which defaults to dist; the finished output must include index.html.
This recipe enables static_spa by default. Turn it off for multi-page content that should return 404 for missing URLs. Do not carry the default from one recipe to the other without checking it.
Use public_build_vars only for public values with supported VITE_, NEXT_PUBLIC_ or PUBLIC_ names, up to 20 keys. Build values become part of the browser bundle. They are not a place for passwords, private API credentials or database connections.
Check port, startup and the page itself
The ready-made-files recipe uses port 8080 by default and supports ports 1024-65535. Its health probe is fixed to /index.html, and require_healthy_start can require startup health on a compatible agent. This is a container readiness check; it does not test every page, link or asset.
After deployment, open the home page, a real deep link and a deliberately nonexistent URL. Confirm that CSS, scripts and images load, and that 404 or SPA behavior matches your choice. Repeat the check on a narrow screen and inspect the final hostname used by absolute asset URLs.
Do not treat an accepted deployment as a successful build. Follow the job to completion and check the served content.
Keep updates predictable
For a Git source, configure automatic deploys on git push when that matches your release process. The source-build recipe rebuilds; the ready-made-files recipe republishes the selected files. Runtime variables cannot rewrite an already generated browser bundle.
Inspect the deployment’s saved recipe and routing settings before changing the project layout. A file update does not automatically change an existing deployment’s strategy. Use configuration review for supported changes to the existing app and review a new deployment where required.
Add an onion address when it fits the site
An eligible app can also use an onion route. Follow publishing a Tor onion site for the route and access controls. Review third-party scripts, fonts, analytics and absolute links: a static page can still make requests to external services and disclose information about the visit.
Read the static-file reference for the current limits. For a compiled Go service instead of a static site, use the Go deployment guide.