Deploying an API in a VPS using Docker ensures that your application runs reliably across various environments. This guide will walk you through the entire process in just five steps, from creating essential files to automating the deployment. Let’s dive in!

Step 1: Create a .dockerignore File

The .dockerignore file helps reduce the Docker image size by excluding unnecessary files and directories. Here’s an example:

__pycache__
venv/
*.pyc
*.pyo
*.pyd
*.git

This file ensures that Python cache files, the virtual environment, and Git metadata are not included in the Docker build.

Step 2: Create a Dockerfile

The Dockerfile defines the environment and steps needed to build your Docker image. For a Flask application, ensure you have a requirements.txt file that lists all dependencies.

requirements.txt (example):

Flask==2.3.3
gunicorn==21.2.0

Dockerfile:

FROM python:3.12.6

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5000

CMD ["gunicorn", "-b" ,"0.0.0.0:5000", "app:app"]

Freezing dependencies: Before building the Docker image, ensure your requirements.txt file is updated by freezing the dependencies:

pip freeze > requirements.txt

If you application uses environment variables create .env file in the root!

Step 3: Connect to Your Remote VPS via SSH

Open your terminal.

Connect to your VPS using SSH:

ssh -i your-key.pem user@your-vps-ip

Replace your-key.pem with your private key and your-vps-ip with your VPS’s IP address.

Step 4: Set Up SSH Access to GitHub

First install Git:

sudo apt install git

To access your private GitHub repository securely, set up an SSH key:

Generate an SSH key:

ssh-keygen -t ed25519 -C "your_email@example.com"

cat ~/.ssh/id_ed25519.pub

Add the public key to your GitHub account:

• Go to GitHub -> Settings -> SSH and GPG keys -> New SSH Key.
• Paste the key and save.

Test the connection:

ssh -T git@github.com

Step 5: Create deployment

Install Docker:

sudo apt update

sudo apt install docker.io

docker --version

# let docker start when symtem boot
sudo systemctl start docker

Automate the deployment process by creating a deploy.sh file in the root. Hit ./deploy.sh in project root and sit back ;) this script pulls the latest code, builds the Docker image, stops running containers, and starts a new container.

or if you want to run it manually hit all the commands pull, build and run 🚀

deploy.sh:

cd ~/pixform/backend

git pull origin main

docker build -t pixform:1.0 .

container_ids=$(docker ps -q --filter "publish=5000")
if [ -n "$container_ids" ]; then
  docker stop $container_ids
  docker rm $container_ids
fi

docker run -d --env-file .env -p 5000:5000 pixform:1.0

if [ $? -ne 0 ]; then
  echo "Port 5000 is already in use, trying port 5001..."
  docker run -d --env-file .env -p 5001:5000 pixform:1.0
fi

echo "Deployment complete!"

Make the Script Executable:

chmod +x deploy.sh

Run the Script:

Run the Script:

Verify Deployment

Check running containers:

docker ps

Verify the application is running by visiting:

http://your-vps-ip:5000

Bonus Docker commands 🙆‍♂️

# to show all created images
docker images

# run docker container by image name:tag
docker run -d --env-file .env -p 5000:5000 <name:tag>
# remove --env-file and .env if your app not required enviroment veriable

# check running containers
# add -a in last for all running and stoped containers
docker ps

# stop running container
docker stop <container-id>

# check container status
docker logs <container-id>

# inspect docker container
docker inspect <container-id>

# show live stats of container
docker stats <container-id>

# delete an image
docker rmi <continer-id>

# executes a command inside a running container.
docker exec -it <container-id> <command>

Happy Coding :)