Deploying a Website with Dokku: A Step-by-Step Guide to Installation, Configuration, and Code Deployment

Dokku, an open-source Platform as a Service (PaaS), empowers developers to effortlessly deploy and manage applications on their infrastructure. If you seek a straightforward method for deploying a basic website, Dokku stands out for its simplicity and user-friendly approach. This guide will navigate you through the steps to set up and deploy a straightforward website using Dokku.

Before we begin this tutorial, make sure you have the following prerequisites in place:

1. Server Setup:

   • Acquire a server or set up a virtual machine with a cloud provider.
   • Install Ubuntu 22.04 x64 on your server.

2. Domain Configuration:

   • Have a domain name pointing to your server's IP address.
   • If not, using the IP address alone suffices.

3. SSH Access:

   • Ensure SSH access to your server.

   • If unfamiliar with connecting through SSH, use the provided commands:

     # at your local computer
     
     # Generate SSH key pair (if not already done)
     ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

     • ssh-keygen: This command generates a new SSH key pair.
     • -t rsa: Specifies the type of key to create, in this case, RSA.
     • -b 4096: Sets the number of bits in the key to 4096, enhancing security.
     • -C "your_email@example.com": Adds a label/comment to the key, typically your email address for identification.
     # at your local computer
     
     # Copy the public key to the server
     ssh-copy-id your_username@your_server_ip

     • ssh-copy-id: Installs your public key on the server, appending it to the ~/.ssh/authorized_keys file of the specified user.
     • your_username: Replace this with your server username.
     • your_server_ip: Replace this with the IP address of your server.
     # at your local computer
     
     # SSH into the server
     ssh your_username@your_server_ip

     • ssh: Initiates an SSH (Secure Shell) session to connect to the server securely.
     • your_username: Replace this with your server username.
     • your_server_ip: Replace this with the IP address of your server.

     Note: If you've set a passphrase during key generation, you'll be prompted to enter it when connecting to the server. The SSH key pair consists of a private key (usually ~/.ssh/id_rsa) and a public key (usually ~/.ssh/id_rsa.pub).

     The public key is copied to the server, while the private key remains securely stored on your local machine. This process enhances security by enabling passwordless, encrypted communication between your local computer and the server.

Start by SSHing into your server and running the following commands to install Dokku:

# download the installation script
 wget -NP . https://dokku.com/bootstrap.sh

# run the installer
 sudo DOKKU_TAG=v0.32.3 bash bootstrap.sh

In this tutorial, note that the latest version of Dokku, as of now, is 0.32.3. Ensure you check the official Dokku website here for the most up-to-date version information. Adjust the version number accordingly in the commands provided.

After successfully installing Dokku, the next step is to configure global settings, such as domains. Whether you have a domain or just an IP address, you can set it up using the terminal:

# Choose any domain you already have access to
# Ensure that this domain has an A record or CNAME pointing to your server's IP
dokku domains:set-global yourdomain.com

# Alternatively, you can use the IP address of your server
dokku domains:set-global 3.3.3.3

Ensure to substitute yourdomain.com with your actual domain and 3.3.3.3 with your server's IP address (I chose 3.3.3.3 simply because I like this number 😎). This configuration is crucial for Dokku to effectively handle and route requests to the respective applications.

SSH into your remote server and create the application with the following commands:

# On the Dokku host
dokku apps:create example-app

Make sure to replace example-app with your desired application name. This step sets up the foundation for deploying your application using Dokku.

You have the flexibility to choose the technology stack for your web app, whether it's pure HTML, CSS, and JS, or a modern framework like Vue or React. For the purpose of this section, I won't provide specific instructions for setting up a React app using Vite. You should build it according to your preferences or requirements. Once you've completed the setup, return here to continue with the deployment process.

To keep things simple and compatible with Dokku's default behavior, we'll need to adjust the project configuration slightly. Dokku typically runs npm run start to start the application, but as Vite does not provide a production-ready build with that command alone, we'll add the serve npm package to facilitate the process.

• Step 1: Install the serve Package

  Install the serve package as a dependency in your project:

npm install --save serve

• Step 2: Update package.json

  Open your package.json file and add a start script that uses serve:

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "start": "serve -s dist"
}

This modification ensures that when Dokku runs npm run start, it will use serve to serve the static files from the dist directory generated by Vite.

Now, your project is configured to work seamlessly with Dokku. Proceed with the deployment steps, and Dokku will use the updated start script to run your application.

Dokku, installed on your server, leverages a Git system for deployment. The deployment process involves reading the Git repository and executing the script specified in package.json. To facilitate this, we need to add a remote Git repository:

git remote add dokku dokku@3.3.3.3:example-app

Explanation:

• git remote add dokku: Adds a remote repository named dokku.
• dokku@3.3.3.3: Specifies the Dokku user and the IP address of your server. Replace 3.3.3.3 with your actual server's IP address.
• example-app: Specifies the name of your Dokku application. Replace it with the actual name you used when creating the Dokku app.

After adding this remote repository, you can use git push dokku main to deploy your application to Dokku. The main branch is assumed here; if you are using a different branch, replace main with the appropriate branch name.

Dokku automates the build process for your code. During this process, you will observe a series of command outputs similar to the following:

Counting objects: 231, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (162/162), done.
Writing objects: 100% (231/231), 36.96 KiB | 0 bytes/s, done.
Total 231 

Be vigilant, as you might encounter some view obstacles during this phase. However, you can closely monitor the outputs and rectify any issues with ease. The provided feedback in the command line will guide you in identifying and addressing potential challenges during the automatic build process.

Congratulations on reaching this point! By following these steps, you've successfully created your first Platform as a Service (PaaS) deployment with Dokku. While it may seem simple, taking this initial step marks the beginning of your PaaS journey. From here, you can explore more advanced configurations, scale your applications, and delve deeper into the capabilities that Dokku offers.

Feel free to explore Dokku's documentation for additional features and optimizations to enhance your PaaS experience. Happy coding!