Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save ChunAllen/04b7244130c5bf8903427e04ae6a47e4 to your computer and use it in GitHub Desktop.
Save ChunAllen/04b7244130c5bf8903427e04ae6a47e4 to your computer and use it in GitHub Desktop.
Deployment manual for a real-world project built with nuxt.js + koa + nginx + pm2

Example of deployment process which I use in my Nuxt.js projects. I usually have 3 components running per project: admin-panel SPA, nuxt.js renderer and JSON API.

This manual is relevant for VPS such as or It's easier to use things like Now for deployment but for most cases VPS gives more flexebillity needed for projects bigger than a landing page.

UPD: This manual now compatible with nuxt@2.3. For older versions deployment, see revision history.

Let's assume that you have entered fresh installation of Ubuntu instance via SSH. Let's rock:

1.Initial setup.

Depending on size of project you have two options: make non-root user or go on with root. I'd suggest you to go with root, which is easier (except nginx part). If you have chosen non-root, check out this tutorial.

2.Install Node.js.

Using nvm or directly:

curl -sL | sudo -E bash -
sudo apt-get install -y nodejs

3.Directory structure

It's actually up to you, depending on type of your project, but I usually use this structure:

  • user dir (ex., /root)
    • config.yml (pm2 config)
    • app (project name)
      • client (nuxt.js files)
      • server (API server files)
      • public (static content)

Fill server dir with your API code, in my case it's nodejs + koa2 + mongoose stack. Place at least favicon and robots.txt to public dir.

4.Upload nuxt.js bundle.

If you use enviroment variables (I hope you are), open package.json file and change build script to "build": "NODE_ENV=production nuxt build", On production build, node.js will pass production flag to your nuxt.config.js. For example, you can make API URL different for dev and prod enviroments and more. Very usefull. (for Windows users, see cross-env package).

Now it's time to make production build. Run npm run build on your local machine. I don't recommend to build nuxt.js on production server, because it eats lots of memory and causes up to minute of downtime. Take package.json, nuxt.config.js and .nuxt dir and copy them via sftp (or pull from git) to client dir.

Note that there is special Nuxt package for running production renderer without useless overhead - nuxt-start. Intall it as dependency with same version as your Nuxt package. Move to your client directory on the server and install production dependencies (in most cases you only need nuxt-start package): npm i -—production.

5.Set up PM2

PM2 is a process manager for node.js. Install PM2 and create config file in your user root dir: config.yml. See config example below. Don't forget to run pm2 save && pm2 startup, so your processes will recover on server restart.

6.Set up Nginx

Install nginx:

sudo apt-get update
sudo apt-get install nginx

(If you use root user, you have to set right permissions for project dirs to make it work with static files. Or just change user: www-data to user: root in /etc/nginx/nginx.conf.) Then edit config file /etc/nginx/sites-available/default, see config example below. Don't forget to sudo nginx -s reload after every nginx config modification.

If you have already connected domain to your project, it's super easy to set up https (and http2). See this tutorial for installing certbot.

7.Fire it up!

Move to dir that contains your pm2 config file and run pm2 start config.yml –-env production. Yay, everything should work now, but it doesn't. Run pm2 logs to see errors. This manual is complicated for a newbie and imperfect itself, so you will probably have to try several times. But it's worth it.

Contributions to this manual are appreciated.

(Don't forget to remove comments)
- name: client # process name. You will use it to make commands such as pm2 restart client
script: node_modules/nuxt-start/bin/nuxt-start.js # path to nuxt-start renderer from root nuxt dir. Don't forget to install nuxt-start dependency
cwd: /root/app/client # absolute path to nuxt dir
max_memory_restart: "250M" # in case nuxt renderer eats all memory, it will be restarted
args: "start" # command to skip build and start renderer
PORT: 3000 # local port. Same port should be set in nginx config
NODE_ENV: production # in case of enviroment variables usage
# API server, if you have one
- name: server
script: app.js
cwd: /root/app/server
PORT: 3001
NODE_ENV: production
server {
listen 80;
listen 443 ssl http2;
# set path to your project dir
set $root_path /root/app;
# your domain
# static content directory
root $root_path/public;
# proxy to nuxt renderer.
location / {
proxy_pass http://localhost:3000;
# entry point for API server, if you have one
location /api {
proxy_pass http://localhost:3001;
client_max_body_size 3m;
# entry point for SPA admin page, if you have one
location /admin {
try_files /admin/index.html =404;
# serve nuxt bundle with max cache life. Only compatible with nuxt 2.*. For 1.*, remove last 'client' from alias
location ~^\/_nuxt(.*)$ {
alias $root_path/client/.nuxt/dist/client/$1;
gzip on;
gzip_comp_level 6;
gzip_vary on;
gzip_types text/css application/json application/javascript text/javascript application/x-font-ttf font/opentype;
expires max;
# serve static content
location ~* \.(js|jpg|jpeg|txt|png|css|pdf|ico|map)$ {
gzip_static on;
expires 30d;
# refirect from /path/ to /path
rewrite ^/(.*)/$ /$1 permanent;
# redirect for domain aliases
server {
return 301 https://$host$request_uri;
# placeholder if user requests your servers' IP.
server {
listen 80 default_server;
listen [::]:80 default_server;
root /var/www/html;
server_name _;
location / {
try_files $uri =404;
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment