Mnoho lidí si myslí, že aplikace Node.js musí běžet na VPS. Nemusí — každý sdílený tarif Rivervo má v nabídce webu sekci Node.js a Python, která pro vaši aplikaci spustí proces Phusion Passenger za stejným front-endem Apache, který obsluhuje vaše ostatní weby.
Tento návod prochází celý postup pro dva nejběžnější frameworky: Next.js a Nuxt 3. Výsledek: vaše aplikace na https://vasedomena.cz (nebo na libovolné subdoméně), běžící ve skutečném procesu Node.js, která přežije restart serveru a jde restartovat jedním kliknutím.
Pokud jste na sdílený hosting aplikaci Node ještě nenasazovali, každý se zasekne na spouštěcím souboru — Passenger potřebuje jeden vstupní skript, který spustí váš framework. Pro každý framework ho najdete níže; stačí zkopírovat, nic neupravujete.
Co potřebujete, než začnete
- tarif hostingu Rivervo (jakýkoli — aplikace Node.js fungují na všech tarifech)
- lokálně Node.js v20 nebo novější pro sestavení aplikace
- sestavenou aplikaci připravenou k nahrání (postup pro jednotlivé frameworky najdete níže)
- přístup ke svému účtu přes správce souborů nebo SFTP (funguje obojí)
Nepotřebujete root, sudo, systemd ani konfiguraci reverzní proxy. To vše zařídí Passenger.
Krok 1 — sestavte aplikaci lokálně
Budete nahrávat sestavenou aplikaci, ne zdrojový kód. Panel nainstaluje závislosti, ale nezkompiluje React ani nespustí build přes Vite. To udělejte nejdřív na svém počítači.
Next.js:
npm ci
npm run buildVznikne .next/ (sestavený výstup). Nespouštějte tady next start — za chvíli aplikaci spustíme ze spouštěcího souboru.
Nuxt 3:
npm ci
npm run buildVznikne .output/ (univerzální adresář buildu Nuxtu). Stejně jako výše — zatím nic nespouštějte.
Krok 2 — nahrajte správné soubory
node_modules/ nahrávat nemusíte. Závislosti za vás nainstaluje panel. Nepotřebujete ani git, ani mezipaměti buildu.
Nahrajte soubory do svého účtu, ideálně do cesty mimo public_html (např. /home/<účet>/myapp/). Proč mimo? Protože Passenger automaticky připojí public_html jako kořen URL a kód aplikace by tam byl veřejně dostupný.
| Framework | Nahrát | Vynechat |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, váš server.cjs (viz níže) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, váš server.cjs (viz níže) | node_modules/, .nuxt/, .git/, zdrojové pages/, components/ |
Soubory tam dostanete dvěma způsoby:
- Web → Soubory → nahrát zip → rozbalit je nejjednodušší, pokud máte nestabilní připojení.
- SFTP (FileZilla, Cyberduck,
rsync) je rychlejší pro opakovaná nasazení. Server, port, uživatele a heslo najdete v sekci Web → SSH a SFTP.
Krok 3 — přidejte spouštěcí soubor
Tento soubor Passenger spouští, když přijde požadavek. Umístěte ho vedle package.json ve složce aplikace.
Pro Next.js — server.cjs
const next = require('next')
const http = require('http')
const port = process.env.PORT || 3000
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev, dir: __dirname })
const handle = app.getRequestHandler()
app.prepare().then(() => {
http.createServer((req, res) => handle(req, res)).listen(port, () => {
console.log(`Next.js server listening on port ${port}`)
})
})Co dělá:
- Načte Next a nasměruje ho na aktuální adresář (kde je vaše
.next/apackage.json). - Vytvoří obsluhu požadavků z interního routeru Next.
- Spustí HTTP server na portu, který přidělí Passenger (
process.env.PORT). - Pro lokální testování použije záložní port
3000.
dev se odvozuje automaticky z NODE_ENV — nastavte v panelu režim Production (uděláme to v kroku 4) a Next poběží v produkčním režimu.
Pro Nuxt 3 — server.cjs
import('./.output/server/index.mjs').then(({ createApp }) => {
createApp().then(({ app }) => {
const port = process.env.PORT || 3000
app.listen(port, () => {
console.log(`Nuxt server listening on port ${port}`)
})
})
})Co dělá:
- Dynamicky importuje
.output/server/index.mjsz Nuxtu (vstupní bod vytvořený příkazemnpm run build). - Pomocí
createApp()vytvoří instanci serveru H3. - Naslouchá na portu přiděleném Passengerem.
Dynamický import() je záměrný — moduly .mjs nelze načíst přes require(), ale soubor .cjs je dynamicky importovat umí. Je to nejčistší vzor, který funguje uvnitř spouštěče Passengeru.
Krok 4 — vytvořte aplikaci v panelu
Otevřete svůj projekt → Web → Node.js a Python → Aplikace Node.js.
| Pole | Hodnota |
|---|---|
| Verze | 20 nebo novější |
| Režim | Production |
| Složka | myapp ve vaší domovské složce (kam jste nahráli soubory) |
| Adresa | vasedomena.cz (nebo subdoména jako app.vasedomena.cz) |
| Spouštěcí soubor | server.cjs |
Klikněte na Vytvořit. V ~/nodevenv/myapp/20/ se vytvoří prostředí Node.js.
Instalace závislostí
Po vytvoření aplikace u ní klikněte na Nainstalovat závislosti (npm install) a sledujte výstup. Pokud selže:
- Zkontrolujte, že
package.jsonje v kořeni aplikace (ne vnořený). - U Next.js: ověřte, že
nextje vdependencies, ne vdevDependencies(produkční instalace vývojové závislosti vynechává). - U Nuxtu: i samotný
nuxtmá být běžnou závislostí.
Přidání proměnných prostředí
Nastavení aplikace → Proměnné prostředí → Přidat proměnnou. Režim Production už nastavuje NODE_ENV=production.
Pro aplikace Next.js, které čtou hodnoty za běhu (adresy databází, API klíče), je přidejte tady. Nenahrávejte soubor .env s tajnými údaji — správné místo jsou proměnné prostředí aplikace.
Uložením nastavení se aplikace restartuje, takže nové proměnné platí okamžitě.
Krok 5 — ověření
Otevřete adresu aplikace. Měli byste vidět svou aplikaci.
Pokud uvidíte chybovou stránku Passengeru, rozbalte ji a podívejte se dolů — téměř vždy tam je srozumitelný výpis zásobníku. Dvě nejčastější chyby:
Error: Cannot find module 'next' — npm install neproběhl, nebo proběhl ve špatné složce. Klikněte znovu na Nainstalovat závislosti (npm install).
Error: ENOENT: no such file or directory, open '.next/...' — nahráli jste zdrojový kód, ale ne sestavený adresář .next/. Sestavte aplikaci lokálně a nahrajte ji znovu.
Jak nasazovat aktualizace
Zopakujte kroky 1 a 2 a u aplikace klikněte na Restartovat. Konkrétně:
1. Lokální build npm run build
2. Nahrání .next/ nebo .output/ a změněné zdrojové a konfigurační soubory
3. Panel Restartovat aplikaciPokud změníte package.json, klikněte před restartem na Nainstalovat závislosti (npm install). Dáváte přednost příkazové řádce? V sekci Web → Terminál karta aplikace ukazuje příkaz pro vstup do jejího prostředí.
Časté záludnosti
WebSockety: Passenger zvládá HTTP/1.1 i HTTP/2. Upgrade na WebSocket funguje pro vestavěné cesty Next.js i Nuxtu. Pokud používáte samostatný WebSocket server (ws, socket.io), sdílí stejný port a spouští se stejným server.cjs — žádná další konfigurace.
Nahrávání souborů / limity body-parser v next.config.js: výchozí limit velikosti těla požadavku v Passengeru je 10 MB. Pokud nahráváte velké soubory, zvyšte passenger_max_request_size přes .htaccess v public_html:
PassengerMaxRequestSize 52428800(50 MB v bajtech.)
Úlohy cron: pokud aplikace potřebuje úlohy na pozadí (rozesílání newsletterů, plánované exporty), nespouštějte je ve webovém procesu. Použijte Web → Úlohy cron a spouštějte skript Node přímo:
/home/<účet>/nodevenv/myapp/20/bin/node /home/<účet>/myapp/scripts/send-newsletter.jsPaměť procesu: Passenger aplikaci restartuje, pokud překročí limit RAM na účet (závisí na tarifu). Typická aplikace Next.js / Nuxt v klidu spotřebuje méně než 100 MB. Pokud narážíte na limity, profilujte pomocí process.memoryUsage() a hledejte úniky paměti dřív, než usoudíte, že potřebujete vyšší tarif.
Vlastní domény a HTTPS: adresa, kterou aplikaci nastavíte, je ta, na kterou se Passenger váže. SSL je automatické — žádná další konfigurace. Pro jinou doménu nebo subdoménu ji nejdřív přidejte v sekci Web → Domény a pak ji vyberte jako adresu aplikace.
Verze Node: seznam Verze ukazuje všechny nainstalované verze; přepnete ji v Nastavení aplikace.
Kdy nepoužívat sdílený hosting pro Node
Upřímně — Node.js na sdíleném hostingu funguje skvěle pro portfolia, blogy, marketingové stránky, front-endy menších SaaS a interní nástroje. Potíže má s:
- API s vysokou propustností (trvale >50 požadavků/s) — narazíte na limit CPU na účet
- aplikacemi náročnými na WebSockety s tisíci souběžných spojení
- aplikacemi, které spouštějí pracovní procesy (zpracování front, scrapery) — limit procesů na účet v Passengeru to komplikuje
- čímkoli, co potřebuje systemd, Docker nebo přístup root
Pro tyto případy je správnou volbou naše VPS — plný root, vlastní jádro, spustíte, co chcete. Pro většinu aplikací Next.js a Nuxt bez obrovské návštěvnosti vám ale tento návod stačí.
Stručně
npm run buildlokálně- Nahrajte
.next/(Next) nebo.output/(Nuxt) +package.json+server.cjs - Web → Node.js a Python → Aplikace Node.js → složka, spouštěcí soubor
server.cjs, režim Production - Nainstalovat závislosti (npm install), pak Restartovat
Pokud něco nefunguje, založte tiket — vložte do něj chybovou stránku Passengeru a ukážeme vám na konkrétní řádek.
— Tým Rivervo