Cara Deploy Python FastAPI di Ubuntu 24.04 LTS

FastAPI adalah web framework Python modern berbasis ASGI, dikenal karena performa tinggi, dukungan async/await native, validasi data otomatis lewat Pydantic, dan dokumentasi API interaktif yang di-generate otomatis dari kode. Panduan ini menjelaskan langkah deploy aplikasi FastAPI di Ubuntu 24.04 LTS, menggunakan paket qVM-2, dengan Gunicorn dan Uvicorn worker sebagai application server, dikelola systemd, dan Nginx sebagai reverse proxy. Pembahasan mencakup instalasi environment server, membangun landing page sekaligus REST API sederhana sebagai studi kasus, konfigurasi systemd service, konfigurasi Nginx, hingga pemasangan SSL gratis menggunakan Let's Encrypt.

Pengenalan

Gunicorn bertindak sebagai process manager yang menjalankan beberapa worker Uvicorn (ASGI server) sekaligus, memanfaatkan banyak core sekaligus memberi fault isolation antar worker. Seluruh proses Gunicorn tersebut kemudian dikelola langsung oleh systemd — mekanisme process supervision bawaan Linux yang menangani auto-restart dan auto-start saat boot. Nginx berperan sebagai reverse proxy, meneruskan request dari domain publik ke aplikasi.

Ubuntu 24.04 LTS sudah menyertakan Python 3.12 secara default, sehingga tidak diperlukan repository tambahan untuk mendapatkan versi Python yang cukup baru. Ubuntu 24.04 LTS sendiri dipilih sebagai basis OS karena mendapat dukungan resmi (security update dan bug fix) hingga April 2029, sehingga sesuai digunakan untuk server aplikasi yang membutuhkan masa pakai jangka panjang. Panduan ini ditujukan untuk VPS atau qVM yang baru saja di-deploy (fresh install) dan belum memiliki konfigurasi tambahan apa pun.

Persyaratan

Sebelum memulai deploy, pastikan hal-hal berikut sudah terpenuhi:

Software

• Ubuntu 24.04 LTS, kondisi fresh install (belum ada web server/service lain yang bentrok port)
• Akses root atau user dengan hak sudo
• Koneksi internet untuk mengunduh paket dari repository Ubuntu, dependensi pip, dan sertifikat SSL
• SSH client pada sisi lokal untuk remote ke qVM
• Project FastAPI yang akan di-deploy (project baru maupun repository Git yang sudah ada)

Hardware / Spesifikasi VPS qVM

Panduan ini menggunakan paket qVM-2, dengan spesifikasi:

• vCPU: 1 core
• RAM: 2 GiB
• Storage: 50 GiB
• Domain yang sudah diarahkan (A record) ke IP Publik qVM — digunakan untuk konfigurasi reverse proxy dan penerbitan sertifikat SSL

Jumlah worker Gunicorn yang disarankan mengikuti formula (2 × jumlah vCPU) + 1. Untuk qVM-2 dengan 1 vCPU, artinya 3 worker adalah titik awal yang wajar. Apabila traffic sudah tinggi atau butuh lebih banyak worker paralel, disarankan upgrade ke paket qVM dengan vCPU lebih banyak.

Tahapan

1. Update dan Upgrade OS Ubuntu 24.04 LTS

Lakukan update dan upgrade pada sistem operasi Ubuntu 24.04 LTS terlebih dahulu, sebelum memulai instalasi service lainnya.

apt update && sudo apt upgrade -y

2. Instalasi Nginx

apt install nginx -y

Aktifkan agar berjalan otomatis saat qVM di-reboot, lalu periksa statusnya:

systemctl enable nginx
systemctl status nginx

Apabila status menunjukkan active (running), Nginx sudah dapat digunakan. Akses http://<IP-qVM> melalui browser untuk memastikan halaman default "Welcome to nginx!" tampil dengan benar.

3. Instalasi Python dan Virtual Environment

Ubuntu 24.04 LTS sudah menyertakan Python 3.12 secara default. Tambahkan modul venv dan pip yang diperlukan untuk mengelola dependency per-project:

apt install python3-venv python3-pip -y

Verifikasi versi Python yang terpasang:

python3 --version

4. Deploy Project FastAPI

Buat direktori project dan virtual environment (venv) — venv mengisolasi dependency Python khusus untuk project ini, terpisah dari package Python milik sistem:

mkdir -p /var/www/fastapi-app
cd /var/www/fastapi-app
python3 -m venv venv
source venv/bin/activate

Instal FastAPI, Uvicorn, dan Gunicorn ke dalam virtual environment:

pip install fastapi uvicorn gunicorn

Apabila project sudah ada di repository Git, gunakan git clone diikuti pembuatan venv dan pip install -r requirements.txt sebagai gantinya.

Atur kepemilikan direktori project:

chown -R $USER:www-data /var/www/fastapi-app

5. Studi Kasus: Landing Page dan REST API Sederhana

Sebagai studi kasus, buat satu file aplikasi yang menyajikan dua hal sekaligus: landing page HTML pada route utama, dan satu endpoint REST API yang mengembalikan JSON.

vim /var/www/fastapi-app/main.py

Isi dengan:

from datetime import datetime, timezone

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.get("/", response_class=HTMLResponse)
def landing_page():
    year = datetime.now().year
    return f"""<!DOCTYPE html>
<html lang="id">
<head>
  <meta charset="UTF-8" />
  <title>Landing Page - KB Sequel</title>
  <style>
    * {{ margin: 0; padding: 0; box-sizing: border-box; }}
    body {{ font-family: 'Segoe UI', Arial, sans-serif; background: #0f172a; color: #f1f5f9; line-height: 1.6; }}
    .hero {{ background: linear-gradient(135deg, #4338ca 0%, #6366f1 50%, #22d3ee 100%); padding: 80px 20px; text-align: center; color: #fff; }}
    .badge {{ display: inline-block; background: rgba(255,255,255,0.15); padding: 6px 16px; border-radius: 999px; font-size: 0.85rem; margin-bottom: 20px; letter-spacing: 0.5px; }}
    .hero h1 {{ font-size: 2.5rem; margin-bottom: 16px; }}
    .hero p {{ font-size: 1.1rem; max-width: 560px; margin: 0 auto 32px; opacity: 0.95; }}
    .btn {{ display: inline-block; background: #fff; color: #4338ca; padding: 14px 32px; border-radius: 999px; font-weight: 600; text-decoration: none; }}
    section {{ padding: 60px 20px; max-width: 1000px; margin: 0 auto; }}
    h2 {{ text-align: center; font-size: 1.8rem; margin-bottom: 12px; }}
    .subtitle {{ text-align: center; color: #94a3b8; margin-bottom: 40px; }}
    .grid {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 24px; }}
    .card {{ background: #1e293b; padding: 26px; border-radius: 16px; border: 1px solid #334155; }}
    .card h3 {{ margin-bottom: 8px; color: #fff; font-size: 1.05rem; }}
    .card p {{ color: #94a3b8; font-size: 0.9rem; }}
    footer {{ text-align: center; padding: 32px 20px; color: #64748b; font-size: 0.9rem; border-top: 1px solid #1e293b; }}
    code {{ background: #1e293b; padding: 2px 8px; border-radius: 6px; }}
  </style>
</head>
<body>
  <section class="hero">
    <span class="badge">KB Sequel &middot; Landing Page Demo</span>
    <h1>Deployment Berhasil</h1>
    <p>Halaman ini adalah contoh landing page FastAPI yang berjalan di atas Gunicorn, Uvicorn worker, dan Nginx reverse proxy, pada paket qVM-2.</p>
    <a href="#status" class="btn">Lihat Status &rarr;</a>
  </section>

  <section id="status">
    <h2>Apa yang Sudah Berjalan?</h2>
    <p class="subtitle">Ringkasan komponen yang sudah dikonfigurasi sampai tahap ini</p>
    <div class="grid">
      <div class="card">
        <h3>Python Aktif</h3>
        <p>Aplikasi FastAPI dijalankan di atas Python 3.12 lewat Gunicorn dan Uvicorn worker.</p>
      </div>
      <div class="card">
        <h3>Systemd Terkelola</h3>
        <p>Proses dikelola langsung oleh systemd — auto-restart dan auto-start saat boot, tanpa PM2.</p>
      </div>
      <div class="card">
        <h3>Nginx Reverse Proxy</h3>
        <p>Permintaan dari domain publik diteruskan Nginx ke aplikasi FastAPI.</p>
      </div>
      <div class="card">
        <h3>REST API Siap</h3>
        <p>Coba endpoint <code>/api/status</code>, atau buka <code>/docs</code> untuk dokumentasi interaktif otomatis.</p>
      </div>
    </div>
  </section>

  <footer>
    <p>Landing page ini adalah contoh deploy FastAPI di atas paket qVM-2.</p>
    <p>&copy; {year} KB Sequel — Semua hak cipta dilindungi.</p>
  </footer>
</body>
</html>"""


@app.get("/api/status")
def status():
    return {
        "status": "ok",
        "stack": "FastAPI",
        "server": "qVM-2",
        "timestamp": datetime.now(timezone.utc).isoformat(),
    }

Route / mengembalikan landing page HTML lewat HTMLResponse, sementara route /api/status mengembalikan dictionary Python yang otomatis di-serialize FastAPI menjadi JSON. Kartu "REST API Siap" pada landing page sekaligus menyebut /docs — FastAPI otomatis meng-generate dokumentasi API interaktif (Swagger UI) dari route yang didefinisikan, tanpa konfigurasi tambahan.

6. Konfigurasi systemd Service untuk Gunicorn

Buat unit file systemd agar Gunicorn berjalan sebagai service — dikelola, di-restart otomatis bila crash, dan aktif kembali setiap qVM reboot.

vim /etc/systemd/system/fastapi-app.service

Isi dengan:

[Unit]
Description=FastAPI application (Gunicorn + Uvicorn workers)
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/fastapi-app
Environment="PATH=/var/www/fastapi-app/venv/bin"
ExecStart=/var/www/fastapi-app/venv/bin/gunicorn main:app -k uvicorn.workers.UvicornWorker -w 3 --bind 127.0.0.1:8000
Restart=always

[Install]
WantedBy=multi-user.target

Nilai -w 3 mengikuti formula (2 × vCPU) + 1 untuk qVM-2 (1 vCPU). Gunicorn di-bind ke 127.0.0.1:8000, hanya bisa diakses dari dalam server — Nginx yang nanti meneruskan request publik ke port tersebut.

Muat ulang systemd, aktifkan, dan jalankan service:

systemctl daemon-reload
systemctl enable fastapi-app
systemctl start fastapi-app
systemctl status fastapi-app

Perintah enable di atas sudah menangani auto-start saat boot.

7. Konfigurasi Nginx sebagai Reverse Proxy

Nginx berperan sebagai reverse proxy, meneruskan request dari domain publik ke Gunicorn yang berjalan pada port 8000.

vim /etc/nginx/sites-available/fastapi.sequel.web.id.conf

Isi dengan konfigurasi berikut:

server {
    listen 80;
    listen [::]:80;
    server_name fastapi.sequel.web.id;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    access_log /var/log/nginx/fastapi-app_access.log;
    error_log /var/log/nginx/fastapi-app_error.log;
}

Aktifkan dengan symlink ke sites-enabled, lalu uji dan reload konfigurasi:

ln -s /etc/nginx/sites-available/fastapi.sequel.web.id.conf /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

8. Uji Akses Aplikasi

Pastikan subdomain yang Anda gunakan sudah dipointing ke IP Publik qVM Anda, contohnya seperti gambar di bawah ini.

Akses http://fastapi.sequel.web.id melalui browser — landing page pada tahap 5 akan tampil. Uji juga endpoint API dengan:

curl http://fastapi.sequel.web.id/api/status

Apabila response berupa JSON berisi status: "ok", berarti seluruh stack (Nginx, Gunicorn, Uvicorn worker, dan systemd) sudah berjalan dengan benar. Buka juga http://fastapi.sequel.web.id/docs untuk melihat dokumentasi API interaktif yang di-generate otomatis oleh FastAPI.

9. Konfigurasi SSL dengan Let's Encrypt

apt install certbot python3-certbot-nginx -y

certbot --nginx -d fastapi.sequel.web.id

Certbot akan meminta email untuk notifikasi perpanjangan, konfirmasi persetujuan term of service, kemudian menawarkan opsi redirect otomatis dari HTTP ke HTTPS — pilih opsi redirect agar seluruh trafik diteruskan melalui HTTPS. Plugin ini secara otomatis mengedit server block yang sudah dibuat pada tahap 7 untuk menambahkan blok listen 443 ssl beserta path sertifikat.

Periksa terlebih dahulu apakah mekanisme perpanjangan (renewal) berjalan dengan normal:

certbot renew --dry-run

Setelah tahap ini, https://fastapi.sequel.web.id sudah dapat diakses dengan koneksi terenkripsi SSL, begitu juga endpoint /api/status dan /docs.

Kesimpulan

Sampai tahap ini, VPS qVM-2 (1 core, 2 GiB RAM, 50 GiB storage) sudah menjalankan aplikasi Python FastAPI yang menyajikan landing page sekaligus REST API sederhana, dijalankan lewat Gunicorn dengan Uvicorn worker, dikelola langsung oleh systemd agar berjalan persisten dan otomatis restart apabila terjadi crash atau server reboot, dengan Nginx sebagai reverse proxy di depannya. Aplikasi telah diamankan dengan SSL gratis dari Let's Encrypt beserta redirect otomatis ke HTTPS. Untuk pengembangan lebih lanjut, langkah yang disarankan adalah memecah route ke router/module terpisah, menambahkan schema Pydantic untuk validasi request/response yang lebih ketat, menghubungkan API ke database lewat SQLAlchemy atau library async seperti asyncpg, menyesuaikan jumlah worker Gunicorn apabila upgrade ke qVM dengan vCPU lebih banyak, dan menyiapkan proses deployment otomatis (CI/CD) yang menjalankan systemctl restart fastapi-app setelah pembaruan kode.