View source for Deploy app bare-metal

Catatan tentang cara deploy aplikasi (Python FastAPI, Rust Actix, Node frontend) langsung di server Ubuntu (contoh: <code>marshall-3</code>) tanpa Docker, memakai '''uv''', '''systemd''', dan '''Ansible'''. Fokus utama catatan ini adalah sisi '''sysadmin''': layout direktori, model user dan permission, hardening service, dan otomasi.

== Gambaran besar ==

Docker memberi tiga hal: '''isolasi''', '''reproducibility''', dan '''packaging'''. Di bare metal, ketiganya tetap bisa didapat dengan alat bawaan Linux:

{| class="wikitable"
! Kebutuhan !! Di Docker !! Di bare metal
|-
| Isolasi proses || namespace, cgroup || user terpisah per app + hardening systemd (juga pakai namespace & cgroup)
|-
| Dependency terkunci || image || lock file (<code>uv.lock</code>, <code>Cargo.lock</code>, <code>package-lock.json</code>) + venv per release
|-
| Restart otomatis || <code>restart: unless-stopped</code> || <code>Restart=on-failure</code> di unit systemd
|-
| Log || <code>docker logs</code> || <code>journalctl -u nama-app</code>
|-
| Rollback || tag image lama || folder release lama + symlink
|-
| Deploy berulang || compose / CI || Ansible
|}

'''Kapan bare metal masuk akal:''' sedikit server, workload GPU, tim kecil, atau binary tunggal (Rust/Go).
'''Kapan Docker lebih unggul:''' banyak server, scaling horizontal, atau dependency sistem yang bentrok antar app (misalnya versi CUDA berbeda per app, karena di bare metal semua app berbagi satu driver NVIDIA).

== Layout direktori (FHS) ==

Setiap app memakai lokasi standar ''Filesystem Hierarchy Standard'', supaya jelas mana kode, mana config, mana data:

{| class="wikitable"
! Path !! Isi !! Kenapa di sini
|-
| <code>/opt/&lt;app&gt;/releases/&lt;versi&gt;/</code> || kode + <code>.venv</code> / <code>target</code> / <code>dist</code> || <code>/opt</code> untuk software tambahan yang bukan dari paket OS
|-
| <code>/opt/&lt;app&gt;/current</code> || symlink ke release aktif || service selalu menunjuk ke sini; ganti versi = ganti symlink
|-
| <code>/etc/&lt;app&gt;/&lt;app&gt;.env</code> || environment variable & secret || <code>/etc</code> untuk konfigurasi milik host, terpisah dari kode
|-
| <code>/var/lib/&lt;app&gt;/</code> || data, cache model, upload, cache uv/cargo/npm || <code>/var/lib</code> untuk state yang ditulis aplikasi saat jalan
|-
| <code>/opt/uv/python/</code> || interpreter Python bersama || dipakai semua app, bukan milik satu user
|-
| <code>/etc/systemd/system/&lt;app&gt;.service</code> || unit service || lokasi unit buatan admin (bukan dari paket)
|}

Pemisahan ini penting untuk permission: '''kode''' boleh read-only saat runtime, '''config''' hanya root yang boleh ubah, dan '''hanya folder data''' yang boleh ditulis aplikasi.

== Model user & permission ==

=== Satu app, satu system user ===

<syntaxhighlight lang="bash">
sudo useradd --system --home-dir /var/lib/transcribe-api \
  --shell /usr/sbin/nologin transcribe
</syntaxhighlight>

* <code>--system</code>: UID diambil dari rentang system (di Ubuntu di bawah 1000), tidak muncul di layar login, dan tidak dibuatkan mailbox atau aging password.
* <code>--shell /usr/sbin/nologin</code>: user tidak bisa login interaktif. Kalau proses app dibobol, penyerang tidak otomatis dapat shell login.
* '''Kenapa per app?''' Kalau satu app bocor, app lain dan file-nya tidak ikut terbaca. Ini prinsip ''least privilege''.

Perintah berguna:
<syntaxhighlight lang="bash">
id transcribe                 # UID, GID, dan group tambahan
getent passwd transcribe      # home & shell
getent group | grep transcribe
sudo -u transcribe -H bash -c 'whoami; echo $HOME'   # tes sebagai user app
</syntaxhighlight>

'''Salah nama user?''' Rename tanpa bikin ulang:
<syntaxhighlight lang="bash">
sudo usermod -l transcribe -d /var/lib/transcribe-api appuser   # ganti login & home
sudo groupmod -n transcribe appuser                            # ganti nama group
</syntaxhighlight>
Karena UID/GID tidak berubah, ownership file otomatis ikut. <code>usermod -d</code> akan gagal kalau user sedang dipakai proses yang jalan, jadi stop service-nya dulu.

Error <code>chown: invalid group: 'root:appuser'</code> artinya group tersebut sudah tidak ada (sudah di-rename atau dihapus). Cek dengan <code>getent group</code>.

=== Tabel ownership & mode ===

{| class="wikitable"
! Path !! Owner:Group !! Mode !! Artinya
|-
| <code>/opt/&lt;app&gt;</code> || root:root || <code>0755</code> || hanya root yang bisa membuat/mengganti symlink <code>current</code>
|-
| <code>/opt/&lt;app&gt;/releases</code> || app:app || <code>0755</code> || user app meng-clone dan build release di sini
|-
| <code>/etc/&lt;app&gt;</code> || root:app || <code>0750</code> || app boleh masuk & baca, user lain tidak bisa melihat isinya
|-
| <code>/etc/&lt;app&gt;/&lt;app&gt;.env</code> || root:app || <code>0640</code> || root tulis, app baca, lainnya tidak bisa apa-apa
|-
| <code>/var/lib/&lt;app&gt;</code> || app:app || <code>0750</code> || satu-satunya tempat app boleh menulis
|-
| <code>/var/lib/&lt;app&gt;/.ssh</code> || app:app || <code>0700</code> || deploy key; SSH menolak key yang permission-nya terlalu terbuka
|-
| <code>/opt/uv/python</code> || root:root || <code>a+rX</code> || semua user boleh baca & eksekusi interpreter, tidak boleh ubah
|}

=== Membaca mode oktal ===

Tiap digit = '''owner''', '''group''', '''others'''. Nilainya jumlah dari <code>r=4</code>, <code>w=2</code>, <code>x=1</code>.

{| class="wikitable"
! Mode !! Owner !! Group !! Others !! Dipakai untuk
|-
| <code>0755</code> || rwx || r-x || r-x || folder publik, binary
|-
| <code>0750</code> || rwx || r-x || --- || folder privat yang boleh dibaca group
|-
| <code>0700</code> || rwx || --- || --- || folder sangat privat (<code>.ssh</code>)
|-
| <code>0640</code> || rw- || r-- || --- || file secret yang dibaca group
|-
| <code>0600</code> || rw- || --- || --- || private key
|}

Untuk '''folder''', bit <code>x</code> artinya "boleh masuk (traverse)", bukan "eksekusi". Tanpa <code>x</code> di folder induk, file di dalamnya tidak bisa diakses walaupun file-nya sendiri <code>r</code>.

<code>chmod -R a+rX</code> (huruf X besar) memberi <code>x</code> hanya ke folder dan file yang sudah executable. Ini cara aman membuka akses baca satu pohon direktori tanpa membuat semua file teks jadi executable.

=== Kenapa env file <code>root:app 0640</code>? ===

* App perlu '''membaca''' secret (DATABASE_URL, SECRET_KEY), tapi tidak perlu '''mengubahnya'''.
* Kalau app dibobol, penyerang tidak bisa mengganti config agar persisten.
* User lain di server tidak bisa membaca secret sama sekali.
* Jangan simpan secret di <code>.env</code> dalam folder kode: gampang ikut ter-commit, dan ikut terbaca siapa pun yang bisa membaca kode.

=== Toolchain bersama & masalah home directory ===

uv bisa meng-install Python sendiri. Defaultnya ke <code>~/.local/share/uv/python</code>. Masalahnya:

* venv '''hanya symlink''' ke interpreter. Kalau interpreter ada di home user A, user B tidak bisa memakainya.
* Unit systemd dengan <code>ProtectHome=true</code> membuat <code>/home</code>, <code>/root</code>, dan <code>/run/user</code> tidak terlihat. Interpreter di home = service gagal start.

Solusinya taruh di lokasi bersama dan buka akses baca:
<syntaxhighlight lang="bash">
export UV_PYTHON_INSTALL_DIR=/opt/uv/python
sudo -E uv python install 3.13
sudo chmod -R a+rX /opt/uv/python
</syntaxhighlight>

Pola yang sama untuk Rust: <code>RUSTUP_HOME=/opt/rust/rustup</code>, <code>CARGO_HOME=/opt/rust/cargo</code>, lalu <code>a+rX</code>. Cache per app (registry cargo, cache uv, cache npm) ditaruh di <code>/var/lib/&lt;app&gt;</code> yang memang writable.

=== Akses GPU ===

Device NVIDIA ada di <code>/dev/nvidia*</code>:
<syntaxhighlight lang="bash">
ls -l /dev/nvidia*
</syntaxhighlight>
Kalau mode-nya <code>crw-rw-rw-</code>, semua user bisa memakai GPU. Kalau hanya group <code>video</code>/<code>render</code>, tambahkan user app ke group tersebut (<code>usermod -aG video transcribe</code>) dan tulis <code>SupplementaryGroups=video</code> di unit. Opsi <code>-a</code> wajib; tanpa itu, group tambahan lain akan terhapus.

=== sudo yang sempit ===

Kalau deploy dijalankan sebagai user app dan perlu restart service, beri izin '''hanya''' untuk perintah itu:

<syntaxhighlight lang="bash">
echo 'transcribe ALL=(root) NOPASSWD: /usr/bin/systemctl restart transcribe-api, /usr/bin/systemctl restart transcribe-api-worker' \
  | sudo tee /etc/sudoers.d/transcribe-api
sudo chmod 0440 /etc/sudoers.d/transcribe-api
sudo visudo -cf /etc/sudoers.d/transcribe-api     # validasi sintaks!
</syntaxhighlight>

* Selalu validasi dengan <code>visudo -c</code>. File sudoers yang rusak bisa mengunci <code>sudo</code> untuk semua orang.
* Path harus absolut dan persis sama. Di Ubuntu modern <code>/bin</code> adalah symlink ke <code>/usr/bin</code>, tapi sudo membandingkan string path, jadi cek dengan <code>command -v systemctl</code>.
* Jangan beri <code>NOPASSWD: ALL</code> ke user app. Itu sama saja memberi root.

Kalau deploy dijalankan lewat Ansible dengan user admin + <code>become</code>, aturan sudoers untuk user app '''tidak diperlukan sama sekali'''.

=== Siapa yang boleh menulis kode? ===

Di setup ini user app yang meng-clone dan build release, jadi kode bisa ditulis oleh user app. Ini sederhana tapi berarti app yang dibobol bisa mengubah kodenya sendiri. Alternatif yang lebih ketat:

* Buat user <code>deployer</code> terpisah yang meng-clone & build semua release.
* User app hanya punya akses baca + eksekusi ke <code>/opt/&lt;app&gt;</code>.
* Bonus: cache uv bisa dipakai bersama antar app, sehingga hardlink menghemat disk (berguna untuk paket besar seperti torch).

Pada level ini, <code>ProtectSystem=strict</code> sudah menahan sebagian besar risiko: saat runtime seluruh filesystem read-only bagi proses app, kecuali <code>ReadWritePaths</code>.

== systemd ==

=== Anatomi unit ===

<syntaxhighlight lang="ini">
[Unit]
Description=Transcribe API
After=network-online.target redis-server.service
Wants=network-online.target redis-server.service

[Service]
Type=simple
User=transcribe
Group=transcribe
SupplementaryGroups=video
WorkingDirectory=/opt/transcribe-api/current
Environment=HOME=/var/lib/transcribe-api
Environment=PORT=6969
EnvironmentFile=-/etc/transcribe-api/transcribe-api.env
ExecStart=/opt/transcribe-api/current/.venv/bin/python -m uvicorn main:app --host 127.0.0.1 --port 6969
Restart=on-failure
RestartSec=5

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/transcribe-api

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Catatan per baris:
* <code>After=</code> mengatur '''urutan''', <code>Wants=</code>/<code>Requires=</code> mengatur '''ketergantungan'''. Hanya <code>After=</code> tidak membuat Redis ikut dijalankan.
* <code>EnvironmentFile=-...</code>: tanda <code>-</code> artinya "jangan gagal kalau file tidak ada". Variabel dari file '''meng-override''' <code>Environment=</code>.
* Format env file systemd: <code>KEY=value</code> per baris, '''tanpa''' <code>export</code>.
* <code>ExecStart</code> harus path absolut. Panggil binary venv langsung, bukan <code>uv run</code>, karena <code>uv run</code> bisa mencoba sync dependency saat start.
* Worker sebaiknya <code>Restart=always</code> dan <code>TimeoutStopSec=120</code> supaya job yang sedang jalan sempat selesai saat restart (systemd mengirim SIGTERM dulu, baru SIGKILL setelah timeout).

=== Directive hardening ===

{| class="wikitable"
! Directive !! Efek
|-
| <code>NoNewPrivileges=true</code> || proses dan turunannya tidak bisa naik hak akses (setuid, file capabilities tidak berlaku)
|-
| <code>ProtectSystem=strict</code> || seluruh filesystem read-only bagi service
|-
| <code>ReadWritePaths=</code> || pengecualian: path yang tetap boleh ditulis
|-
| <code>ProtectHome=true</code> || <code>/home</code>, <code>/root</code>, <code>/run/user</code> tidak terlihat
|-
| <code>PrivateTmp=true</code> || <code>/tmp</code> privat per service, tidak berbagi dengan proses lain
|}

Ukur tingkat keamanan unit:
<syntaxhighlight lang="bash">
systemd-analyze security transcribe-api
</syntaxhighlight>
Output-nya memberi skor dan daftar directive lain yang bisa ditambahkan (misalnya <code>ProtectKernelTunables</code>, <code>RestrictAddressFamilies</code>). Tambahkan bertahap dan tes, karena hardening yang terlalu ketat bisa mematahkan app (misalnya akses GPU butuh device yang tidak diblokir <code>PrivateDevices</code>).

=== Operasional harian ===

<syntaxhighlight lang="bash">
sudo systemctl daemon-reload                     # wajib setelah edit file unit
sudo systemctl enable --now transcribe-api       # aktif saat boot + jalan sekarang
systemctl status transcribe-api transcribe-api-worker
journalctl -u transcribe-api -u transcribe-api-worker -f    # follow log
journalctl -u transcribe-api --since "1 hour ago" -p err    # hanya error
systemctl cat transcribe-api                      # lihat unit final yang dipakai
</syntaxhighlight>

=== Exit code systemd yang sering muncul ===

{| class="wikitable"
! Status !! Penyebab umum
|-
| <code>status=203/EXEC</code> || path di <code>ExecStart</code> salah, file tidak executable, atau venv rusak (interpreter yang di-symlink tidak bisa diakses)
|-
| <code>status=217/USER</code> || user di <code>User=</code> tidak ada
|-
| <code>status=200/CHDIR</code> || <code>WorkingDirectory</code> tidak ada atau tidak bisa dimasuki user app
|-
| <code>status=226/NAMESPACE</code> || path di <code>ReadWritePaths</code> belum dibuat
|-
| <code>Permission denied</code> di log app || app menulis di luar <code>ReadWritePaths</code> (cache model, file upload); arahkan ke <code>/var/lib/&lt;app&gt;</code>
|}

== Pola release + symlink ==

<pre>
/opt/transcribe-api/
├── releases/
│   ├── 3f2a9c1d7e0b/
│   └── 9be41c0a22f1/
└── current -> releases/3f2a9c1d7e0b
</pre>

Alur deploy:
# Clone versi baru ke <code>releases/&lt;sha&gt;</code>.
# Build (<code>uv sync --locked --no-dev</code>, <code>cargo build --release --locked</code>, <code>npm ci && npm run build</code>).
# Jalankan migrasi database kalau ada.
# Arahkan <code>current</code> ke release baru, restart service.
# Health check. Gagal → arahkan kembali ke release lama.

'''Soal atomik:''' <code>ln -sfn</code> sebenarnya menghapus symlink lalu membuat ulang, sehingga ada jeda sangat singkat tanpa <code>current</code>. Cara yang benar-benar atomik:
<syntaxhighlight lang="bash">
ln -s /opt/app/releases/NEW /opt/app/current.tmp
mv -T /opt/app/current.tmp /opt/app/current     # rename(2) atomik
</syntaxhighlight>

'''Venv tidak bisa dipindah.''' Path absolut tertanam di script dalam <code>.venv/bin</code>, jadi selalu build venv langsung di folder release, jangan build di tempat lain lalu di-copy.

== Python dengan uv ==

* <code>uv sync --locked</code> gagal kalau <code>uv.lock</code> tidak sinkron dengan <code>pyproject.toml</code>. Ini yang diinginkan di produksi: server tidak pernah mengubah lock file.
* <code>--no-dev</code> melewati dependency development/test.
* <code>UV_PYTHON_DOWNLOADS=never</code> mencegah uv diam-diam mengunduh Python saat build.
* Update dependency dilakukan di laptop: <code>uv lock --upgrade</code>, commit, lalu deploy.
* Cache uv memakai hardlink ke venv selama berada di filesystem yang sama, sehingga deploy berikutnya cepat dan hemat disk.

== Redis lokal ==

<syntaxhighlight lang="bash">
sudo apt install -y redis-server
sudo sed -i 's/^appendonly no/appendonly yes/' /etc/redis/redis.conf   # persistence
grep -E '^(bind|appendonly)' /etc/redis/redis.conf                     # bind 127.0.0.1 -::1
sudo systemctl enable --now redis-server
redis-cli ping
</syntaxhighlight>
Redis tanpa password '''wajib''' hanya listen di localhost. Di Docker, hostname-nya <code>redis</code>; di bare metal jadi <code>redis://127.0.0.1:6379/0</code>.

== Jaringan ==

* <code>--host 127.0.0.1</code>: app hanya bisa diakses dari server itu sendiri (cocok kalau nginx ada di server yang sama).
* <code>--host 0.0.0.0</code>: app bisa diakses dari luar. Wajib dibarengi firewall.
* Kalau nginx publik ada di VM proxy terpisah, buka port app '''hanya untuk IP VM proxy''':

<syntaxhighlight lang="bash">
sudo ufw allow OpenSSH
sudo ufw allow from 192.168.88.10 to any port 6969 proto tcp comment 'transcribe-api'
sudo ufw enable
sudo ufw status numbered
</syntaxhighlight>

Ubuntu memakai '''AppArmor''', bukan SELinux seperti AlmaLinux/RHEL. Untuk app di <code>/opt</code> biasanya tidak perlu konfigurasi tambahan.

== Otomasi dengan Ansible ==

=== Kenapa Ansible ===
* '''Agentless''': cukup SSH + Python di server.
* '''Idempotent''': dijalankan berkali-kali hasilnya sama; hanya yang berubah yang diubah.
* Semua langkah manual di atas terdokumentasi sebagai kode, sehingga server bisa dibangun ulang kapan saja.

=== Struktur project ===

<pre>
ansible-apps/
├── inventory.ini            daftar server
├── apps.yml                 daftar app (repo, port, worker)
├── deploy.yml               playbook utama
├── group_vars/all/main.yml  setting global
├── group_vars/all/vault.yml secret terenkripsi
├── scripts/new-app.sh       tambah app interaktif
└── roles/
    ├── base/                paket dasar
    ├── redis/
    ├── python_toolchain/    uv + Python di /opt/uv/python
    ├── rust_toolchain/      rustup di /opt/rust
    ├── node_toolchain/      NodeSource
    └── app/                 clone, deteksi tipe, build, systemd/nginx, health check, rollback
</pre>

=== Entry app ===

<syntaxhighlight lang="yaml">
apps:
  - name: transcribe-api
    repo: git@github.com:org/transcribe-api.git
    version: main
    port: 6969
    user: transcribe
    worker: true          # bikin service transcribe-api-worker
    redis: true
    apt_packages: [ffmpeg]
    extra_groups: [video]
    health_path: /health
</syntaxhighlight>

Tipe app dideteksi dari isi repo: <code>pyproject.toml</code> → Python, <code>Cargo.toml</code> → Rust, <code>package.json</code> → Node (Vite/React jadi static di-serve nginx, Next/Nuxt jadi service).

=== Perintah ===

<syntaxhighlight lang="bash">
ansible-playbook deploy.yml                                   # semua app
ansible-playbook deploy.yml -e only=transcribe-api            # satu app
ansible-playbook deploy.yml -e only=core-api -e rev=v1.2.0    # versi tertentu / rollback
ansible-playbook deploy.yml --syntax-check
ansible-vault encrypt group_vars/all/vault.yml
</syntaxhighlight>

=== Konsep Ansible yang terkait permission ===

* <code>become: true</code>: task dijalankan sebagai root lewat sudo.
* <code>become_user: transcribe</code>: task dijalankan sebagai user app (clone, build), sehingga file yang dihasilkan langsung dimiliki user yang benar tanpa <code>chown</code> belakangan.
* Paket <code>acl</code> wajib terpasang. Saat <code>become_user</code> ke user non-root, Ansible menulis file modul sementara lalu memakai ACL (<code>setfacl</code>) agar user tujuan bisa membacanya.
* Modul <code>file</code> dengan <code>owner</code>, <code>group</code>, <code>mode</code> menggantikan rangkaian <code>mkdir</code>/<code>chown</code>/<code>chmod</code> dan idempotent.
* Secret di '''ansible-vault''', dirender ke env file lewat modul <code>template</code> dengan mode <code>0640</code>.

=== Deploy key untuk repo private ===

* Satu key per app, disimpan di <code>/var/lib/&lt;app&gt;/.ssh/id_ed25519</code> (mode <code>0600</code>, folder <code>0700</code>).
* Didaftarkan sebagai '''Deploy Key read-only''' di repo. Kalau server bocor, yang terekspos hanya akses baca ke satu repo, bukan akun GitHub pribadi.
* <code>StrictHostKeyChecking=accept-new</code>: host key disimpan saat pertama kali, dan koneksi ditolak kalau host key berubah (proteksi MITM).

== Troubleshooting ==

{| class="wikitable"
! Gejala !! Penyebab !! Solusi
|-
| <code>chown: invalid group</code> || group sudah di-rename/dihapus || <code>getent group</code>, pakai nama baru
|-
| <code>useradd</code> menghasilkan shell aneh || sisa <code>\</code> line-continuation ikut diketik dalam satu baris || cek <code>getent passwd</code>, bikin ulang user
|-
| Service <code>203/EXEC</code> padahal file ada || venv menunjuk ke Python di home user lain || install Python di <code>/opt/uv/python</code>, buat ulang venv
|-
| Model Whisper gagal diunduh || cache di luar <code>ReadWritePaths</code> || set <code>WHISPER_CACHE_DIR</code> / <code>HF_HOME</code> ke <code>/var/lib/&lt;app&gt;</code>
|-
| <code>libcudnn</code> / <code>libcublas</code> not found || di Docker library datang dari image || install paket pip <code>nvidia-cudnn-cu12</code> / <code>nvidia-cublas-cu12</code> atau CUDA toolkit di host
|-
| Worker restart terus || error di job pertama atau Redis belum jalan || <code>journalctl -u app-worker -n 100</code>, <code>redis-cli ping</code>
|-
| Ansible gagal <code>become_user</code> || paket <code>acl</code> belum terpasang || <code>apt install acl</code>
|}

== Checklist server baru ==

* [ ] User admin pakai SSH key, login password dimatikan
* [ ] <code>ufw</code> aktif, hanya SSH + port yang perlu
* [ ] Driver NVIDIA terpasang, <code>nvidia-smi</code> jalan (kalau ada GPU)
* [ ] <code>unattended-upgrades</code> aktif untuk patch keamanan
* [ ] Jalankan <code>ansible-playbook deploy.yml</code>
* [ ] <code>systemd-analyze security &lt;app&gt;</code> untuk tiap service
* [ ] Backup data di <code>/var/lib/&lt;app&gt;</code> dan database, '''tes restore'''

== Lihat juga ==
* [https://docs.astral.sh/uv/ Dokumentasi uv]
* [https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html systemd.exec (directive hardening)]
* [https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html Filesystem Hierarchy Standard 3.0]
* [https://docs.ansible.com/ Dokumentasi Ansible]