paulh
/
adobe-to-docusign-migrator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Compare commits

base: paulh:683a64158ead25050c4393dec39d1f98cce35ca2
Branches Tags
paulh:master
paulh:ui-redesign
...
compare: paulh:dd7a041820f28f97fce37caacbfb27c4498badc6
Branches Tags
paulh:master
paulh:ui-redesign

2 Commits
683a64158e ... dd7a041820

Author SHA1 Message Date
Paul Huliganga dd7a041820 docs: add Oracle VM deploy cheat sheet 2026-04-21 17:10:58 -04:00
Paul Huliganga 7258984386 docs: add Oracle VM deployment guide 2026-04-21 17:09:17 -04:00
2 changed files with 726 additions and 0 deletions
Show Stats Expand all files Collapse all files

207
docs/oracle-vm-deploy-cheat-sheet.md Normal file
View File

@ -0,0 +1,207 @@
# Oracle VM Deploy Cheat Sheet — Adobe Sign → DocuSign Migrator
_Last updated: 2026-04-21_
This is the short version of the deployment process.
Use this when you already know what you are doing and just need the commands.
---
## Local project path
```bash
cd /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
```
## 1. Check what changed
```bash
git status
git branch --show-current
```
## 2. Run tests
Full suite:
```bash
pytest tests/ -v
```
Quick 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
```
## 3. Commit and push
```bash
git add .
git commit -m "Describe the change"
git push origin <branch-name>
```
If deploying `master`:
```bash
git push origin master
```
---
## 4. SSH to Oracle VM
Using IP:
```bash
ssh ubuntu@<VM_PUBLIC_IP>
```
Using hostname:
```bash
ssh ubuntu@dstemplate.mooo.com
```
---
## 5. Pull latest code on VM
```bash
cd /home/ubuntu/projects/adobe-to-docusign-migrator
git branch --show-current
git status
```
Deploy `master`:
```bash
git checkout master
git pull origin master
```
Deploy a feature branch intentionally:
```bash
git checkout <branch-name>
git pull origin <branch-name>
```
---
## 6. Update dependencies
```bash
cd /home/ubuntu/projects/adobe-to-docusign-migrator
source venv/bin/activate
pip install -r requirements.txt
```
---
## 7. Restart app
```bash
sudo systemctl restart adobe-migrator
sudo systemctl status adobe-migrator --no-pager
```
---
## 8. Smoke test on VM
App health:
```bash
curl http://127.0.0.1:8000/health
```
HTML through nginx:
```bash
curl http://127.0.0.1/
```
---
## 9. Check logs if broken
```bash
journalctl -u adobe-migrator -n 100 --no-pager
journalctl -u adobe-migrator -f
```
Check nginx:
```bash
sudo nginx -t
sudo systemctl reload nginx
```
---
## 10. Important paths
Local project:
```bash
/home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
```
VM project:
```bash
/home/ubuntu/projects/adobe-to-docusign-migrator
```
Service file:
```bash
/etc/systemd/system/adobe-migrator.service
```
Nginx site:
```bash
/etc/nginx/sites-available/dstemplate
/etc/nginx/sites-enabled/dstemplate
```
Public URL:
```text
http://dstemplate.mooo.com
```
---
## One-block deploy command set
If code is already pushed and you are deploying `master`:
```bash
ssh ubuntu@dstemplate.mooo.com '
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 &&
curl -s http://127.0.0.1:8000/health
'
```
---
## Safety reminders
- Know which branch you are deploying
- Run tests first
- Commit before deploy
- Don’t overwrite `.env`, `.env-adobe`, or `private.key` casually
- If the site breaks, check `journalctl -u adobe-migrator`

519
docs/oracle-vm-deployment.md Normal file
View File

@ -0,0 +1,519 @@
# Deploying the Adobe Sign → DocuSign Migrator to the Oracle Cloud VM
_Last updated: 2026-04-21_
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
```
These should **not** be overwritten casually.
They likely contain:
- Adobe Sign credentials
- DocuSign credentials
- refresh tokens / secrets
- app configuration
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
At the time this doc was written:
- local workspace branch: `ui-redesign`
- Oracle VM branch: `master`
So deployment should be done intentionally.
Do not assume the VM is following your current local branch automatically.
---
## 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. **Restart the systemd service after code changes.**
7. **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