StaraTrace Operations Runbook

Runbook ini ditujukan untuk operator/deployer agar tidak perlu menebak command saat menjalankan, merawat, atau mendistribusikan aplikasi.

1. Pilih mode lingkungan

Local non-Docker

python manage.py migrate
python manage.py runserver

Docker production utama

docker compose --env-file .env.production -f docker-compose.production.yml up -d

Docker distribution / server pihak ketiga

Web saja:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml up -d

Web + AI:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml --profile ai up -d

Web + AI + external upload:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml --profile ai --profile external-upload up -d

2. Kalau .env.production diubah

Container harus direcreate agar env baru terbaca:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml up -d

Atau untuk stack production utama:

docker compose --env-file .env.production -f docker-compose.production.yml up -d

Tidak perlu rebuild image bila hanya env yang berubah.

3. Command Django di Docker

Jalankan command dari service web.

System check

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py check

Migration

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py migrate

Buat admin

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py createsuperuser

Rebuild search index

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py rebuild_search_index

4. Worker

Biasanya worker tidak perlu dijalankan manual kalau sudah memakai Docker Compose dengan profile yang sesuai. Tapi untuk troubleshooting, command dasarnya:

AI summary worker

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py run_ai_summary_worker --once --limit 10

External upload worker

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py run_external_upload_worker --once

External upload worker dry-run

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py run_external_upload_worker --once --dry-run

5. Cleansing dan purge

Reset data operasional

Preview dulu:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py cleanse_operational_data --dry-run

Eksekusi:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py cleanse_operational_data

Fungsi: - hapus data operasional core/ingest - kosongkan storage app - user/auth management tetap dipertahankan

Gunakan hanya untuk reset environment non-production atau UAT.

Purge soft delete setelah masa retensi

Preview:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py purge_soft_deleted --dry-run

Eksekusi:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml exec web python manage.py purge_soft_deleted

Catatan: - purge hanya menghapus record yang sudah soft-delete - default retensi: 30 hari

5a. Scheduler maintenance

Default:

MAINTENANCE_SCHEDULER_ENABLED=False

Saat nilai ini False, halaman Sync untuk user staff akan menampilkan tombol:

Sync Semua Maintenance

Tombol ini menjalankan tiga maintenance sekaligus: - reroute staged email yang sekarang sudah match pattern terbaru - check_external_source_links --requeue-repairable - purge_soft_deleted

Saat nanti scheduler diaktifkan:

MAINTENANCE_SCHEDULER_ENABLED=True

tombol manual akan disembunyikan agar operator tidak perlu menjalankan langkah yang sama dua kali.

6. Script yang dipakai operator

Deploy ke VPS utama

Lokal Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\deploy_vps.ps1

Catatan: - script deploy sekarang rebuild semua service compose, bukan hanya web - jika transfer scp pertama gagal, script otomatis retry dengan mode legacy scp -O - proses docker compose up --build -d di server dijalankan di background dan dipantau lewat log remote agar sesi SSH panjang tidak mudah putus

File konfigurasi:

deploy/vps.env
deploy/distribusi.env

Bootstrap template lokal:

copy deploy\vps.env.example deploy\vps.env
copy deploy\distribusi.env.example deploy\distribusi.env

Export image dari VPS aktif

Lokal Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\export_distribution_images_from_vps.ps1

Output lokal:

dist/distribution/<timestamp>/

Catatan penting: - export remote default diarahkan ke /tmp/staratrace-dist-exports - jangan simpan file .tar distribusi di root project VPS, karena bisa membengkakkan Docker build context pada deploy berikutnya

Bootstrap login SharePoint

Local/non-container:

python scripts/sharepoint_rpa_login.py --start-url "https://tenant.sharepoint.com/sites/example/Shared%20Documents/Forms/AllItems.aspx"

Test runner upload eksternal tanpa SharePoint asli

python scripts/external_upload_runner_stub.py --echo-success

7. Distribusi image ke server lain

Di server sumber / mesin yang punya image

docker save -o staratrace-web.tar staratrace-web:latest
docker save -o staratrace-ai-summary-worker.tar staratrace-ai-summary-worker:latest
docker save -o staratrace-external-upload-worker.tar staratrace-external-upload-worker:latest

Di server tujuan

docker load -i staratrace-web.tar
docker load -i staratrace-ai-summary-worker.tar
docker load -i staratrace-external-upload-worker.tar

Lalu isi: - .env.distribution - .env.production

Kemudian jalankan:

docker compose --env-file .env.distribution -f docker-compose.distribution.yml --profile ai --profile external-upload up -d

8. SharePoint RPA state

Kalau external upload memakai sesi login reuse, file state harus ada di server target:

storage/rpa/sharepoint_state.json

Jika belum ada: - copy dari server lama - atau login ulang dengan sharepoint_rpa_login.py

9. Pengecekan cepat saat ada masalah

Lihat status container

docker compose --env-file .env.distribution -f docker-compose.distribution.yml ps

Lihat log web

docker compose --env-file .env.distribution -f docker-compose.distribution.yml logs -f web

Lihat log AI worker

docker compose --env-file .env.distribution -f docker-compose.distribution.yml logs -f ai-summary-worker

Lihat log external upload worker

docker compose --env-file .env.distribution -f docker-compose.distribution.yml logs -f external-upload-worker

Tes endpoint app lokal container

curl -I http://127.0.0.1:8006/
curl -I http://127.0.0.1:8006/admin/login/

10. Routing subject pattern

Untuk Email subject patterns:

  • porto = subject mengandung porto
  • porto* = subject dimulai dengan porto
  • porto && fsd = subject harus mengandung porto dan fsd, urutan bebas

Catatan: - && hanya berlaku dalam satu baris - antar baris tetap berarti OR

Contoh:

porto && fsd
ksei && review

Artinya subject boleh cocok ke salah satu rule di atas.

11. Kebijakan file setelah external upload sukses

Saat ini, file lokal tidak dihapus otomatis setelah RPA sukses upload ke target URL.

File baru hilang jika: 1. record di-soft-delete 2. retensi terlewati 3. command purge_soft_deleted dijalankan

12. Checklist harian operator

  1. Pastikan web hidup.
  2. Jika AI dipakai, pastikan ai-summary-worker hidup.
  3. Jika external upload dipakai, pastikan external-upload-worker hidup.
  4. Intake email melalui upload atau IMAP sync.
  5. Review staged email bila ada.
  6. Cek document diff dan AI summary.
  7. Lihat log worker jika ada job gagal.