[nmakarevich-prog]

Description

Expand the existing is*hosting deployment guide with step-by-step instructions for deploying static and server-side rendered (SSR) Astro sites on a VPS.

The update covers:

• VPS prerequisites and Node.js installation
• Astro SSR configuration with the Node.js adapter
• Running SSR applications with PM2 and Nginx
• Static site deployment using Nginx
• HTTPS configuration with Certbot
• Updating deployed Astro sites

The guide also includes properly formatted code blocks and links to relevant resources.

References

• Related to the existing is*hosting deployment guide.
• Astro version: Current version supported by Astro Docs.
• Discord username: natashamakarevish85

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the tracking.ignoredKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
guides/deploy/ishosting.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. Once a maintainer approves our workflows, you’ll be able to see a preview of your changes on Cloudflare 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[github-actions]

Preview deployment

🔄 Deployment in progress...

• Latest commit: f0e6547
• Preview: https://patch-1.previews.docs.astro.build
• Workflow run: View logs

[ArmandPhilippot]

Thank you for this helpful content!

I left some suggestions mostly to improve consistency with the rest of the docs (components, wording, structure), to condense a bit the step, and to avoid versions where we can to be more future proof (e.g. Node v22 when use x.y.z elsewhere is easy to miss when Astro will no longer be compatible with v22).

We also try to be as concise as we can when the information is already available in another source (e.g. is*hosting blog post) to reduce maintenance cost on Astro-side. Our goal is generally to provide a happy path by indicating only the minimum steps required.

I hope my suggestions don't cause any important information to be lost. Feel free to adapt them if they're not good enough!

[nmakarevich-prog]

Thank you for your helpful feedback! I agree with all your suggestions and appreciate your guidance on making the guide more concise and consistent with the rest of the Astro documentation.

[ArmandPhilippot]

Thanks a lot for the updates. 🙌🏽

I don't have a strong opinion for the "Project configuration" section; it was mostly a consistency nit. However, we still need some changes for the deploy instructions to match what we do in the other pages of the docs and our contribution guidance.

Since I'm not sure what was the exact issues with my suggestion, I didn't offer a new one. But I have described what we should update to match Astro Docs style.

I'm sorry, I know this seems like a lot of work to update, but my goal is to ensure consistency across all Astro Docs pages and avoid confusion for users navigating between pages. Some older guides don't follow all these recommendations (it's on my to-do list!). But we strive to ensure that new content follows them. I hope you understand. 💜

[ArmandPhilippot]

Hmm, okay. I suppose it's a matter of interpretation. In my mind "Prerequisites" are the "technical requirements", and a user needs to know that before running astro add node.

What worried me more was the consistency and user expectations when consulting different guides (e.g. some older guides such as Deno Deploy already place "Prerequisites"/"Requirements" first.)

But, this was non-blocking! You're free to disagree. 😄

[nmakarevich-prog]

Thanks for the clarification! I’ve adopted your changes and the shorter version of the deployment instructions. Could you please let me know if anything else is required from my side before the pull request? вт, 20 окт. 2026 г. в 16:28, Armand Philippot ***@***.***>:

…

***@***.**** commented on this pull request. Thanks a lot for the updates. 🙌🏽 I don't have a strong opinion for the "Project configuration" section; it was mostly a consistency nit. However, we still need some changes for the deploy instructions to match what we do in the other pages of the docs and our contribution guidance. Since I'm not sure what was the exact issues with my suggestion, I didn't offer a new one. But I have described what we should update to match Astro Docs style <https://contribute.docs.astro.build/>. I'm sorry, I know this seems like a lot of work to update, but my goal is to ensure consistency across all Astro Docs pages and avoid confusion for users navigating between pages. Some older guides don't follow all these recommendations (it's on my to-do list!). But we strive to ensure that new content follows them. I hope you understand. 💜 ------------------------------ In src/content/docs/en/guides/deploy/ishosting.mdx <#14739 (comment)>: > + + A VPS is suitable when your Astro site uses SSR and requires a persistent server, database connections, background jobs, cron jobs, or API routes. + + ## Project Configuration + + Your Astro project can be deployed to an is\*hosting VPS as a static site or as a server-side rendered site (SSR). + + ### Static Site + + Your Astro project is a static site by default. You don't need any extra Astro configuration to deploy a static site to an is\*hosting VPS. + + ### Adapter for SSR + + To enable on-demand rendering in your Astro project and deploy it to an is\*hosting VPS, add [the Node.js adapter](/en/guides/integrations-guide/node/). + + ## Prerequisites Hmm, okay. I suppose it's a matter of interpretation. In my mind "Prerequisites" are the "technical requirements", and a user needs to know that before running astro add node. What worried me more was the consistency and user expectations when consulting different guides (e.g. some older guides such as Deno Deploy <https://docs.astro.build/en/guides/deploy/deno/> already place "Prerequisites"/"Requirements" first.) But, this was non-blocking! You're free to disagree. 😄 ------------------------------ In src/content/docs/en/guides/deploy/ishosting.mdx <#14739 (comment)>: > + + 7. Verify that the process is running: + + ```shell + pm2 status + ``` + + 8. Configure PM2 to restore the process after a server restart: + + ```shell + pm2 startup + ``` + + Run the command printed by PM2, then save the current process list: + + ```shell + pm2 save + ``` + + 9. Create an Nginx configuration for your Astro site: + + ```shell + nano /etc/nginx/sites-available/astro + ``` + + 10. Add the following configuration, replacing `your.domain.com` with your domain: + + ```nginx + server { + listen 80; + server_name your.domain.com; + + location / { + proxy_pass http://127.0.0.1:4321; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + ``` + + 11. Enable the Nginx configuration and reload Nginx: + + ```shell + ln -s /etc/nginx/sites-available/astro /etc/nginx/sites-enabled/astro + nginx -t + systemctl reload nginx + ``` + + + Your Astro SSR site is now served through Nginx, which forwards incoming requests to the Node.js process running on `127.0.0.1:4321`. + + ## Deploy a Static Astro Site + + For a static Astro site, build your project and serve the generated `dist/` directory directly with Nginx. A persistent Node.js process is not required. + + 1. Copy or clone your Astro project to the VPS, install its dependencies, and build the site: + + ```shell + cd /var/www + git clone YOUR_REPOSITORY_URL astro + cd astro + npm install + npm run build + ``` + + 2. Create an Nginx configuration: + + ```shell + nano /etc/nginx/sites-available/astro + ``` + + 3. Add the following configuration, replacing `your.domain.com` with your domain: + + ```nginx + server { + listen 80; + server_name your.domain.com; + + root /var/www/astro/dist; + index index.html; + + location / { + try_files $uri $uri/ $uri.html =404; + } + } + ``` + + 4. Enable the configuration and reload Nginx: + + ```shell + ln -s /etc/nginx/sites-available/astro /etc/nginx/sites-enabled/astro + nginx -t + systemctl reload nginx + ``` + + + Your static Astro site is now served directly from the generated `dist/` directory. Ah, sorry for any accuracy lost! But, no worries, you don't have to apply my suggestion if you don't like it! However, we still cannot publish this as is and you might want to push your own changes instead: - Prerequisites is not a place where we give instructions; this should be a short list of technical requirements <https://contribute.docs.astro.build/guides/new-third-party-guide/#:~:text=Most%20newer,as>, and that's why I suggested to wrap this in a "How to deploy" section <https://contribute.docs.astro.build/guides/new-third-party-guide/#:~:text=a%20deployment%20guide%20should%20have%20a%20step%2Dby%2Dstep%20%E2%80%9CHow%20to%20Deploy%E2%80%9D%20section> - We avoid mentioning Node.js versions as much as possible, because it is difficult to maintain and it is easier to manage a few places to update. (both for us and our translators). That's why I suggested to put it in the prerequisites with a link to Astro own requirements instead of here. We don't want to say "Node.js 22" somewhere when Astro will no longer support it (and because we usually use x.y.z versions, it's easy to miss). - The "Project configuration" already say on-demand rendered websites requires the Node.js adapter and we should not repeat that here; prerequisites are here to help make the steps minimal <https://contribute.docs.astro.build/guides/new-third-party-guide/#:~:text=purpose%20of%20these%20guides%20is%20to%20minimally%20demonstrate%20the%20process> - We still need to wrap the commands in <PackageManagerTabs /> <https://contribute.docs.astro.build/reference/custom-components/#custom-tabs-components> and steps in <Steps /> <https://contribute.docs.astro.build/reference/custom-components/#steps-component> - It's more than okay to give opinionated instructions <https://contribute.docs.astro.build/guides/writing-style/#opinionated-instructions>, but we should explain this is an example using Nginx and PM2 as there are other ways to deploy (e.g. Apache, Docker, a systemd service). That's why I suggested to put that as an intro of the "How to deploy" section. - When the code snippet <https://contribute.docs.astro.build/reference/code-samples/#file-name-as-title> is a file, we show its path in a title attribute - We should make the headings consistent and use "sentence case" here - nit: When we have similar sets of instructions, we try to extract them so that we have a single place to update when needed. That's why I suggested a "Set up your VPS" section. But, you're free to ignore that if you don't like it. — Reply to this email directly, view it on GitHub <#14739?email_source=notifications&email_token=B6TSPKQ5XHZFA44KREBAGXD5U5R6TA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJYGUYDIMJUGYYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-5585041460>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B6TSPKXTNU37VP2LFCCE6R35U5R6TAVCNFSNUABFKJSXA33TNF2G64TZHMZTONZTG43TCMRSHNEXG43VMU5TKOBYGMYTCOJWHEZ2C5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/B6TSPKWAJGYDAUX6Y3H6FQD5U5R6TA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJYGUYDIMJUGYYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/B6TSPKSOXX4FBKL2QMDA3B35U5R6TA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJYGUYDIMJUGYYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[ArmandPhilippot]

Thank you again, and welcome to Team Docs! 🥳

Everything looks good to me. I left a new suggestion for the reordering since you seem to agree with that. I haven't applied it in case you want to double check.

[nmakarevich-prog]

Thank you again! Everything looks good! 🤩 вт, 20 окт. 2026 г. в 17:44, Armand Philippot ***@***.***>:

…

***@***.**** approved this pull request. Thank you again, and welcome to Team Docs! 🥳 Everything looks good to me. I left a new suggestion for the reordering since you seem to agree with that. I haven't applied it in case you want to double check. ------------------------------ In src/content/docs/en/guides/deploy/ishosting.mdx <#14739 (comment)>: > + ## Project configuration + + Your Astro project can be deployed to an is\*hosting VPS as a static site or as an on-demand rendered site. + + ### Static site + + Your Astro project is a static site by default. You don't need any extra Astro configuration to deploy a static site to an is\*hosting VPS. + + ### Adapter for on-demand rendering + +To enable on-demand rendering in your Astro project, add [the Node.js adapter](/en/guides/integrations-guide/node/) with the following `astro add` command. This will install the adapter and configure it in `standalone` mode in your `astro.config.mjs` file in one step. + +<PackageManagerTabs> + <Fragment slot="npm"> + ```shell + npx astro add node + ``` + </Fragment> + <Fragment slot="pnpm"> + ```shell + pnpm astro add node + ``` + </Fragment> + <Fragment slot="yarn"> + ```shell + yarn astro add node + ``` + </Fragment> +</PackageManagerTabs> + + ## Prerequisites + + To deploy your Astro site to an is\*hosting VPS, you will need: + + - An Astro project + - An is\*hosting VPS running Ubuntu with SSH access and `root` or `sudo` privileges + - A domain name pointing to your VPS +- A Node.js version that meets [Astro's minimum requirements](/en/install-and-setup/#prerequisites) installed on your VPS This should work (I only swapped the two sections): ⬇️ Suggested change - ## Project configuration - - Your Astro project can be deployed to an is\*hosting VPS as a static site or as an on-demand rendered site. - - ### Static site - - Your Astro project is a static site by default. You don't need any extra Astro configuration to deploy a static site to an is\*hosting VPS. - - ### Adapter for on-demand rendering - -To enable on-demand rendering in your Astro project, add [the Node.js adapter](/en/guides/integrations-guide/node/) with the following `astro add` command. This will install the adapter and configure it in `standalone` mode in your `astro.config.mjs` file in one step. - -<PackageManagerTabs> - <Fragment slot="npm"> - ```shell - npx astro add node - ``` - </Fragment> - <Fragment slot="pnpm"> - ```shell - pnpm astro add node - ``` - </Fragment> - <Fragment slot="yarn"> - ```shell - yarn astro add node - ``` - </Fragment> -</PackageManagerTabs> - - ## Prerequisites - - To deploy your Astro site to an is\*hosting VPS, you will need: - - - An Astro project - - An is\*hosting VPS running Ubuntu with SSH access and `root` or `sudo` privileges - - A domain name pointing to your VPS -- A Node.js version that meets [Astro's minimum requirements](/en/install-and-setup/#prerequisites) installed on your VPS + ## Prerequisites + + To deploy your Astro site to an is\*hosting VPS, you will need: + + - An Astro project + - An is\*hosting VPS running Ubuntu with SSH access and `root` or `sudo` privileges + - A domain name pointing to your VPS +- A Node.js version that meets [Astro's minimum requirements](/en/install-and-setup/#prerequisites) installed on your VPS + + ## Project configuration + + Your Astro project can be deployed to an is\*hosting VPS as a static site or as an on-demand rendered site. + + ### Static site + + Your Astro project is a static site by default. You don't need any extra Astro configuration to deploy a static site to an is\*hosting VPS. + + ### Adapter for on-demand rendering + +To enable on-demand rendering in your Astro project, add [the Node.js adapter](/en/guides/integrations-guide/node/) with the following `astro add` command. This will install the adapter and configure it in `standalone` mode in your `astro.config.mjs` file in one step. + +<PackageManagerTabs> + <Fragment slot="npm"> + ```shell + npx astro add node + ``` + </Fragment> + <Fragment slot="pnpm"> + ```shell + pnpm astro add node + ``` + </Fragment> + <Fragment slot="yarn"> + ```shell + yarn astro add node + ``` + </Fragment> +</PackageManagerTabs> — Reply to this email directly, view it on GitHub <#14739?email_source=notifications&email_token=B6TSPKVBZN7MAWH7QCXMCT35U525JA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJYGY3DSNRSHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-5586696281>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B6TSPKTMPGYTZMM623Z55S35U525JAVCNFSNUABFKJSXA33TNF2G64TZHMZTONZTG43TCMRSHNEXG43VMU5TKOBYGMYTCOJWHEZ2C5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/B6TSPKUAJUV76O3PMGISIXT5U525JA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJYGY3DSNRSHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/B6TSPKXK2X53YRPC4U2TZB35U525JA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJYGY3DSNRSHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>