adobe-to-docusign-migrator/docs/oracle-vm-deployment.md

# Deploying the Adobe Sign → DocuSign Migrator to the Oracle Cloud VM

_Last updated: 2026-04-21 (post-deploy note added)_

This document explains:
1. the **current live deployment setup** on the Oracle VM
2. how to **deploy updated app code**
3. how to **restart and verify** the site
4. where the important config files live

This is written so future-you does not have to rediscover the setup.

---

## 1. Current Live Deployment Setup

### Server
The app is currently deployed to an Oracle Cloud Ubuntu VM.

### Live app directory
```bash
/home/ubuntu/projects/adobe-to-docusign-migrator
```

### Process manager
The app is run by **systemd** as a service named:
```bash
adobe-migrator.service
```

### App server
The service launches the FastAPI app with `uvicorn`:
```bash
/home/ubuntu/projects/adobe-to-docusign-migrator/venv/bin/uvicorn web.app:app --host 0.0.0.0 --port 8000
```

### Reverse proxy
**nginx** listens on port 80 and proxies traffic to the app on port 8000.

### Live hostname
```text
dstemplate.mooo.com
```

### Nginx site config
```bash
/etc/nginx/sites-available/dstemplate
/etc/nginx/sites-enabled/dstemplate
```

### Systemd service file
```bash
/etc/systemd/system/adobe-migrator.service
```

---

## 2. Current Service Configuration

The current systemd service file is:

```ini
[Unit]
Description=Adobe Sign to DocuSign Migrator
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/projects/adobe-to-docusign-migrator
ExecStart=/home/ubuntu/projects/adobe-to-docusign-migrator/venv/bin/uvicorn web.app:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5
Environment=PATH=/home/ubuntu/projects/adobe-to-docusign-migrator/venv/bin

[Install]
WantedBy=multi-user.target
```

What this means:
- the app runs as user `ubuntu`
- the working directory is the project folder
- it uses the project’s Python virtual environment
- if the app crashes, systemd restarts it automatically

---

## 3. Current Nginx Configuration

The live nginx site config is:

```nginx
server {
    listen 80;
    server_name dstemplate.mooo.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}
```

What this means:
- visitors go to `http://dstemplate.mooo.com`
- nginx receives the request on port 80
- nginx forwards it to the FastAPI app on `127.0.0.1:8000`

---

## 4. Environment and Secrets on the VM

The deployment relies on environment files stored in the app directory.

Important files on the VM:
```bash
/home/ubuntu/projects/adobe-to-docusign-migrator/.env
/home/ubuntu/projects/adobe-to-docusign-migrator/.env-adobe
/home/ubuntu/projects/adobe-to-docusign-migrator/private.key
/home/ubuntu/projects/adobe-to-docusign-migrator/.session-store/
```

These should **not** be overwritten casually.
They likely contain:
- Adobe Sign credentials
- DocuSign credentials
- refresh tokens / secrets
- app configuration
- active browser-session files for concurrent testers

Before a risky deploy, back them up.

Example:
```bash
cd /home/ubuntu/projects/adobe-to-docusign-migrator
cp .env .env.backup
cp .env-adobe .env-adobe.backup
cp private.key private.key.backup
```

---

## 5. Current Git Situation

### On local workstation
The project currently exists at:
```bash
/home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
```

### On Oracle VM
The deployed copy currently exists at:
```bash
/home/ubuntu/projects/adobe-to-docusign-migrator
```

### Important note
Current expected deployment flow:
- local workspace deployment branch: `master`
- Oracle VM deployment branch: `master`

So deployment should be done intentionally.
Do not assume the VM is following your current local branch automatically.

### SSH note for new machines
If you SSH to `dstemplate.mooo.com` from a machine that has never connected before, you may need to accept or record the server host key first.

Example:
```bash
ssh-keyscan -H dstemplate.mooo.com >> ~/.ssh/known_hosts
```

Then connect normally:
```bash
ssh ubuntu@dstemplate.mooo.com
```

---

## 6. Standard Deployment Procedure

This is the recommended clean deployment flow.

### Step 1: Review local changes
On your local machine:

```bash
cd /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
git status
```

Make sure you understand:
- what changed
- which branch you are on
- whether the changes are ready to ship

### Step 2: Run tests locally
Before deploying, run the tests that matter.

For the full test suite:

```bash
cd /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
pytest tests/ -v
```

For a quicker smoke test:

```bash
pytest tests/test_api_health.py -v
pytest tests/test_api_auth.py -v
pytest tests/test_api_templates.py -v
pytest tests/test_api_migrate.py -v
```

If you changed frontend files only, still run at least a small backend smoke test.

### Step 3: Commit your changes locally
```bash
cd /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
git add .
git commit -m "Describe the deployment-worthy change"
```

### Step 4: Push to the remote repo
```bash
git push origin <branch-name>
```

If deploying from `master`:
```bash
git push origin master
```

If deploying from a feature branch:
- either merge it first
- or intentionally deploy that branch on the VM

### Step 5: SSH into the Oracle VM
```bash
ssh ubuntu@<VM_PUBLIC_IP>
```

Or if DNS is set up and working:
```bash
ssh ubuntu@dstemplate.mooo.com
```

### Step 6: Go to the app directory on the VM
```bash
cd /home/ubuntu/projects/adobe-to-docusign-migrator
```

### Step 7: Check current branch and status
```bash
git branch --show-current
git status
```

If the VM has local changes, stop and inspect before pulling.

### Step 8: Pull the code you want to deploy
If deploying `master`:
```bash
git checkout master
git pull origin master
```

If deploying a feature branch intentionally:
```bash
git checkout <branch-name>
git pull origin <branch-name>
```

### Step 9: Update Python dependencies
Use the project virtual environment.

```bash
cd /home/ubuntu/projects/adobe-to-docusign-migrator
source venv/bin/activate
pip install -r requirements.txt
```

If requirements did not change, this is still safe to run.

### Step 10: Restart the service
```bash
sudo systemctl restart adobe-migrator
```

### Step 11: Confirm the service is healthy
```bash
sudo systemctl status adobe-migrator --no-pager
```

You want to see:
- `active (running)`

### Step 12: Test locally on the VM
```bash
curl http://127.0.0.1:8000/health
```

and/or:

```bash
curl http://127.0.0.1/
```

If nginx is working, the second command should return HTML for the app.

### Step 13: Test from a browser
Open:
```text
http://dstemplate.mooo.com
```

Verify:
- the page loads
- CSS/JS load correctly
- authentication buttons still work
- the main workflow still renders

---

## 7. Fast Deploy Shortcut

Once you are confident in the process, this is the shortest safe deploy sequence on the VM after code has been pushed:

```bash
cd /home/ubuntu/projects/adobe-to-docusign-migrator
git checkout master
git pull origin master
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart adobe-migrator
sudo systemctl status adobe-migrator --no-pager
```

---

## 8. How to Inspect the Current Live Deployment

### Check service status
```bash
sudo systemctl status adobe-migrator --no-pager
```

### Restart service
```bash
sudo systemctl restart adobe-migrator
```

### Stop service
```bash
sudo systemctl stop adobe-migrator
```

### Start service
```bash
sudo systemctl start adobe-migrator
```

### View recent service logs
```bash
journalctl -u adobe-migrator -n 100 --no-pager
```

### Follow live logs
```bash
journalctl -u adobe-migrator -f
```

### Check nginx config
```bash
sudo nginx -t
```

### Reload nginx
```bash
sudo systemctl reload nginx
```

### Check which process is listening on port 8000
```bash
ss -ltnp | grep 8000
```

---

## 9. Troubleshooting

### Problem: service restarted but site still broken
Check:
```bash
journalctl -u adobe-migrator -n 100 --no-pager
```

Common causes:
- missing Python dependency
- bad `.env` value
- import error in code
- startup crash in FastAPI app

### Problem: nginx returns 502 Bad Gateway
Usually means nginx cannot reach the app on port 8000.

Check:
```bash
sudo systemctl status adobe-migrator --no-pager
curl http://127.0.0.1:8000/health
```

If the health check fails, the app is not running correctly.

### Problem: static files not loading
Check:
- app HTML returns successfully
- browser dev tools for 404s on `/static/...`
- FastAPI static mounting still exists

### Problem: pulled wrong branch
Check:
```bash
git branch --show-current
git rev-parse HEAD
```

### Problem: secrets got overwritten
Restore from backup if you made one:
```bash
cp .env.backup .env
cp .env-adobe.backup .env-adobe
cp private.key.backup private.key
sudo systemctl restart adobe-migrator
```

---

## 10. Manual One-Off Deploy Without Git Pull

If for some reason you need to copy a local working tree directly instead of using Git:

### From local machine
```bash
rsync -av --exclude '.git' --exclude 'venv' \
  /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator/ \
  ubuntu@<VM_PUBLIC_IP>:/home/ubuntu/projects/adobe-to-docusign-migrator/
```

Then on the VM:
```bash
cd /home/ubuntu/projects/adobe-to-docusign-migrator
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart adobe-migrator
```

Use this carefully. Git-based deployment is cleaner.

---

## 11. Recommended Deployment Rules

1. **Always know what branch you are deploying.**
2. **Run tests before deploy.**
3. **Commit before deploy.**
4. **Prefer Git pull on the VM over manual file copying.**
5. **Do not overwrite `.env`, `.env-adobe`, or `private.key` unless intended.**
6. **Do not casually delete `.session-store/` during active testing.**
7. **Restart the systemd service after code changes.**
8. **Smoke test both localhost and the public URL.**

---

## 12. Quick Reference

### Local project path
```bash
/home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
```

### VM project path
```bash
/home/ubuntu/projects/adobe-to-docusign-migrator
```

### Service file
```bash
/etc/systemd/system/adobe-migrator.service
```

### Nginx site config
```bash
/etc/nginx/sites-available/dstemplate
/etc/nginx/sites-enabled/dstemplate
```

### Restart app
```bash
sudo systemctl restart adobe-migrator
```

### Check app status
```bash
sudo systemctl status adobe-migrator --no-pager
```

### Check logs
```bash
journalctl -u adobe-migrator -n 100 --no-pager
```

### Public URL
```text
http://dstemplate.mooo.com
```

---

## 13. Future Improvements

Possible future upgrades for deployment:
- HTTPS with Let’s Encrypt
- deployment script (`deploy.sh`)
- backup/rollback script
- CI/CD from Gitea
- separate staging environment
- branch-based preview deploys