Production-Ready Vue 3 (Vite) Deployment on Ubuntu with Nginx

Transitioning a Vue 3 application built with Vite from local development to a live, production-ready server requires a methodical approach. This guide will walk you through the essential steps to deploy your Vue (Vite) application on an Ubuntu server, leveraging Nginx for optimal performance and reliable serving of static assets.

Prerequisites

Before we begin, ensure you have the following:

An Ubuntu server (e.g., version 20.04 LTS or 22.04 LTS) with SSH access.
A non-root user with sudo privileges configured on your server.
Basic familiarity with the Linux command line.
Your Vue 3 application built with Vite, ready for production.

Step 1: Initial Server Setup

Start by updating your server's package list and upgrading installed packages.

sudo apt update
sudo apt upgrade -y

Install Node.js and npm

Vite applications require Node.js and npm (or yarn) to build. We recommend using nvm (Node Version Manager) for easy management of Node.js versions.

Install nvm:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

Note: Replace v0.39.1 with the latest version available if needed. Close and reopen your SSH session or run source ~/.bashrc (or ~/.zshrc) to load nvm.

Install Node.js:

nvm install --lts
nvm use --lts
node -v
npm -v

This will install and use the latest LTS version of Node.js and its bundled npm.

Install Nginx

Nginx is a high-performance web server that will serve your Vue application's static files and handle incoming requests.

sudo apt install nginx -y
sudo ufw allow 'Nginx HTTP'
sudo systemctl start nginx
sudo systemctl enable nginx

Verify Nginx is running by navigating to your server's IP address in a web browser. You should see the default Nginx welcome page.

Configure Firewall (UFW)

Ensure your firewall (UFW) allows necessary traffic.

sudo ufw enable
sudo ufw allow ssh
sudo ufw allow 'Nginx HTTP'
# If you plan to use HTTPS later, also allow:
# sudo ufw allow 'Nginx HTTPS'
sudo ufw status

Step 2: Prepare Your Vue Application for Deployment

Build Your Application

On your local machine, navigate to your Vue project directory and run the production build command. This will compile your Vue components, optimize assets, and generate static files in a dist directory.

npm run build

Transfer Application Files to the Server

You have a few options for transferring your dist folder to the server:

SCP (Secure Copy Protocol): Simple for one-time transfers.

scp -r dist user@your_server_ip:/var/www/your_domain/

Git: Recommended for continuous deployment. Clone your repository directly onto the server.

We'll proceed with the Git method as it's more robust for updates.

On your server:

cd /var/www/
sudo mkdir your_domain
sudo chown -R $USER:$USER /var/www/your_domain
cd your_domain
git clone https://github.com/your-username/your-repo.git .
npm install
npm run build

Note: Replace your_domain and the Git repository URL with your actual details. The . at the end of git clone clones into the current directory. Ensure your server has git installed (sudo apt install git -y).

The production-ready static files will now reside in /var/www/your_domain/dist.

Step 3: Configure Nginx to Serve Your Application

Nginx needs to be configured to point to your application's dist directory and handle Vue Router's history mode.

Create a new Nginx configuration file:

sudo nano /etc/nginx/sites-available/your_domain

Add the following configuration:

server {
    listen 80;
    server_name your_domain www.your_domain;

    root /var/www/your_domain/dist;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Optional: Cache control for static assets (e.g., 7 days)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }

    error_log /var/log/nginx/your_domain_error.log warn;
    access_log /var/log/nginx/your_domain_access.log;
}

Replace your_domain and www.your_domain with your actual domain name. The try_files directive is crucial for Vue Router's history mode, ensuring that direct access to sub-paths (e.g., /about) or page refreshes on sub-paths are correctly routed back to index.html.

Create a symbolic link to enable the site:

sudo ln -s /etc/nginx/sites-available/your_domain /etc/nginx/sites-enabled/

Test Nginx configuration for syntax errors:

sudo nginx -t

If successful, you should see syntax is ok and test is successful.

Restart Nginx to apply changes:

sudo systemctl restart nginx

Now, when you visit http://your_domain in your web browser, your Vue application should be live!

Step 4: Secure Your Application with HTTPS (Optional but Recommended)

For production, securing your application with an SSL certificate is paramount. Let's Encrypt provides free SSL certificates, and Certbot automates the process.

Install Certbot:

sudo apt install certbot python3-certbot-nginx -y

Obtain and install SSL certificate:

sudo certbot --nginx -d your_domain -d www.your_domain

Follow the prompts. Certbot will automatically modify your Nginx configuration to include HTTPS and set up automatic renewal.

Verify HTTPS:

sudo ufw allow 'Nginx HTTPS'
sudo ufw reload

Visit https://your_domain to confirm your site is now secure.

Deployment Workflow & Updates

For future updates to your application, the workflow will typically involve:

On your local machine, make changes and commit them to your Git repository.
Push your changes to your remote Git repository (e.g., GitHub, GitLab).
On your server, navigate to your application's directory (/var/www/your_domain).
Pull the latest changes:

git pull

Install any new dependencies and rebuild the application:

npm install
npm run build

Since Nginx is serving the dist folder, and the folder contents are updated, Nginx will automatically serve the new files without a restart (unless you change Nginx config itself).

Conclusion

You've successfully deployed your Vue 3 (Vite) application to an Ubuntu server using Nginx, configured for production readiness, and secured with HTTPS. This robust setup provides a solid foundation for your application. For further enhancements, consider exploring continuous integration/continuous deployment (CI/CD) pipelines to automate your deployment workflow even further.

Happy deploying!