Deployment to Linux server

[Daniel15]

I was surprised to see that the deployment guide explains how to deploy to a bunch of "fancy" services, but doesn't explain anything about how to deploy to a regular Linux server. The closest thing is the Hostinger guide, which says to use FTP using FileZilla for a static site, or deploy from Git (or manually upload) for a site with dynamic parts.

I'd like to contribute a guide that uses rsync, Nginx, and systemd. However, I'm trying to understand the best approach to take to deploy an Astro site.

For a purely static site, it's easy: rsync the dist directory to the server, then configure it like any other static site in Nginx.

For a site with on-demand or server-rendered site, it's more difficult. We can use systemd to run the server-side code, but getting it into a state where it can run on the server is what I'm trying to figure out.

With C#, I run dotnet publish and the resulting publish directory contains everything that's needed on the production site - compiled C# app, dependencies, and the built JS and CSS for the site. I thought astro build would perform similarly, but the server-side code in dist isn't standalone as it still requires node_modules.

I was thinking of some approaches:

• rsync the entire site (or check it out using Git) then use astro build on the server. It works, but it's not great... A production server shouldn't also be a build environment.
• Use esbuild or similar to build the server into a single JS file. This could be combined with Node SEA (single executable applications) to build the site into a single executable. I haven't tried it.
• rsync dist to the server, copy across package.json and the lock file, and run npm install --omit=dev to only install the packages that are required in prod.

The last one seems like the most reasonable approach. It's still not perfect since the production server needs to have npm on it, but it's not too bad. It would be useful if Astro could copy the package.json file to the dist directory itself rather than me having to do that.

Does the Astro team have a preferred approach for deploying to a regular server?

[ArmandPhilippot]

Hi, thanks for starting this discussion!

This is tricky because there is no preferred approach, and given all the possibilities, we cannot be exhaustive.

As you noted, for a fully static website, rsync is a possibility, but not all hosting providers allow it. So, FileZilla could be another option, and sometimes the hosting provider only allows file transfers through its own panel.

For hybrid or on-demand rendered websites:
Currently, dist/ is not portable and some paths may be broken if you build locally and then upload dist/. There is an open discussion to add support for this, and IIRC, there is also a draft PR to implement it. (and I assume that's why Astro doesn't copy package.json in dist)
So, the recommended approach would be to build on the server using the Node adapter. Then, in standalone mode, you simply need to run node ./dist/server/entry.mjs. You can do this manually, with systemd, or with tools like PM2.
You can also use Docker! In fact, we also have a recipe for building with Docker, including configuration for Apache and Nginx. This means you can build your Docker image locally, push it to a registry, then simply pulling the new image on your server.

So it's true that currently, deployment guides focus solely on deployment services. We can't cover all this: we only document what is specific to Astro to reduce maintenance cost.

Perhaps we could add a section on the Deployment overview to provide minimal guidance (ie. links to the Docker recipe and Node adapter) for solutions such as VPS or shared hosting.

As for complete instructions, I'm more hesitant. We could consider adding a new recipe, but I'm not sure there's an approach that's universal enough to be a good recipe.

However, we always appreciate community blog posts explaining how someone did something! Once published, this could also be linked from Astro Tips, a community website.

[Daniel15]

not all hosting providers allow it.

I was thinking of a guide just for servers where you have SSH access, for example a VPS or dedicated server.

Currently, dist/ is not portable and some paths may be broken if you build locally and then upload dist/.

Ohh, I didn't know this. I'm glad to see other people think this is an issue too. I'll follow the discussion/issue you linked to :)

You can also use Docker! In fact, we also have a recipe for building with Docker, including configuration for Apache and Nginx. This means you can build your Docker image locally, push it to a registry, then simply pulling the new image on your server.

This is a good approach. Is there a reason the Docker recipe isn't linked from the https://docs.astro.build/en/guides/deploy/? As a user, that's where I'd except to find a link to Docker instructions.

I think the approach I'd take is to use the Docker container just for the server-side code, and serve the static files from Nginx on the VPS normally (not via Docker).

We can't cover all this: we only document what is specific to Astro to reduce maintenance cost.

I was looking through a few of the deployment guides, and the Hostinger and Heroku guides (and probably others) aren't really Astro-specific.

I'm not sure there's an approach that's universal enough to be a good recipe.

Yeah... that's true. I was thinking the docs would only include the most popular way of running web apps on Linux: Nginx for the webserver, Node.js adapter, and systemd for running the Node.js app.

[ArmandPhilippot]

I was thinking of a guide just for servers where you have SSH access, for example a VPS or dedicated server.
[...]
Yeah... that's true. I was thinking the docs would only include the most popular way of running web apps on Linux: Nginx for the webserver, Node.js adapter, and systemd for running the Node.js app.

I don't know if this is the most popular way, at least for Node.js app (when I started PM2 was trending, then Docker, then... I don't know, I'm still using Docker 😄 ). But, this sounds like a good approach for a recipe! If we do that, I think we could have a tab for Nginx and another one for Apache (as on the Docker recipe), to help more people.

However, uploading package.json into dist on the server sounds more like a hacky workaround at the moment. At least, this doesn't look like something we want to officially document.

I mean everything in docs is the "official way". If it doesn't work for everyone, it generates more maintenance work, either to correct a documented use case, or to correct the documentation... and I'm not sure this should be in docs right now.
When dist will be portable, I'll probably be less hesitant. I hope you understand. (this doesn't mean I'm closing the discussion! let's see what other people think)

Ohh, I didn't know this. I'm glad to see other people think this is an issue too. I'll follow the discussion/issue you linked to :)

Not sure what the status on this, but the draft PR is here. Maybe this is just exploration work, but at least this is considered.

Is there a reason the Docker recipe isn't linked from the https://docs.astro.build/en/guides/deploy/? As a user, that's where I'd except to find a link to Docker instructions.

Not to my knowledge. The only good reason I can see is: limited resources. It's hard to keep track of everything and we might not think of every places when we add/move/remove docs. So, feedback are always helpful and welcome!

This page has barely been updated since I joined. And I agree, this sounds like a good place to redirect to deploy related stuff. This was also my expectation the first time I used Astro. But, recipes were maybe more visible at that time... and no one had complained. So, thank you for sharing your experience!

And, yes, as I said earlier, I think a new section providing minimal advice with links to redirect people to existing docs resources is good thing! At the moment, I can only think about the Node adapter and the Docker recipe...
If you have any ideas about what this section should look like, feel free to share them. I don't work full-time on Astro and we're quite busy at the moment (a clue), but happy to think more about this after!

I was looking through a few of the deployment guides, and the Hostinger and Heroku guides (and probably others) aren't really Astro-specific.

Right. Heroku is an old guide so I wouldn't take it as a reference. (the caution at the top is a clue 😅). But, yes, Hostinger is new.

When I said "Astro-specific", I meant how to make Astro work with the deployment platform. And, yes, using a FTP client is not Astro-specific, but apparently this is how Hostinger works. That's said, we don't document how to use Filezilla. Maybe this guide could have been condensed by redirecting directly to their docs. I don't know. It's always tricky to judge the right balance when you don't know the platform.

Sorry, I'm not sure my thinking is clearer...

Anyway, that's why, I'm hesitant to talk about rsync or Nginx config. If it gets straight to the point (and it seems you have a good approach in mind), maybe it's fine. I'm simply sharing my doubt here! I think a recipe might be helpful, but once dist/ is portable.