paulh
/
adobe-to-docusign-migrator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
adobe-to-docusign-migrator/docs/oracle-vm-deployment.md

10 KiB
Raw Blame History

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

/home/ubuntu/projects/adobe-to-docusign-migrator

Process manager

The app is run by systemd as a service named:

adobe-migrator.service

App server

The service launches the FastAPI app with uvicorn:

/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

dstemplate.mooo.com

Nginx site config

/etc/nginx/sites-available/dstemplate
/etc/nginx/sites-enabled/dstemplate

Systemd service file

/etc/systemd/system/adobe-migrator.service

2. Current Service Configuration

The current systemd service file is:

[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:

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:

/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:

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:

/home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator

On Oracle VM

The deployed copy currently exists at:

/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:

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:

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

For a quicker smoke test:

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

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

git push origin <branch-name>

If deploying from master:

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

ssh ubuntu@<VM_PUBLIC_IP>

Or if DNS is set up and working:

ssh ubuntu@dstemplate.mooo.com

Step 6: Go to the app directory on the VM

cd /home/ubuntu/projects/adobe-to-docusign-migrator

Step 7: Check current branch and status

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:

git checkout master
git pull origin master

If deploying a feature branch intentionally:

git checkout <branch-name>
git pull origin <branch-name>

Step 9: Update Python dependencies

Use the project virtual environment.

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

sudo systemctl restart adobe-migrator

Step 11: Confirm the service is healthy

sudo systemctl status adobe-migrator --no-pager

You want to see:

  • active (running)

Step 12: Test locally on the VM

curl http://127.0.0.1:8000/health

and/or:

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:

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:

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

sudo systemctl status adobe-migrator --no-pager

Restart service

sudo systemctl restart adobe-migrator

Stop service

sudo systemctl stop adobe-migrator

Start service

sudo systemctl start adobe-migrator

View recent service logs

journalctl -u adobe-migrator -n 100 --no-pager

Follow live logs

journalctl -u adobe-migrator -f

Check nginx config

sudo nginx -t

Reload nginx

sudo systemctl reload nginx

Check which process is listening on port 8000

ss -ltnp | grep 8000

9. Troubleshooting

Problem: service restarted but site still broken

Check:

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:

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:

git branch --show-current
git rev-parse HEAD

Problem: secrets got overwritten

Restore from backup if you made one:

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

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:

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

/home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator

VM project path

/home/ubuntu/projects/adobe-to-docusign-migrator

Service file

/etc/systemd/system/adobe-migrator.service

Nginx site config

/etc/nginx/sites-available/dstemplate
/etc/nginx/sites-enabled/dstemplate

Restart app

sudo systemctl restart adobe-migrator

Check app status

sudo systemctl status adobe-migrator --no-pager

Check logs

journalctl -u adobe-migrator -n 100 --no-pager

Public URL

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