For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

OpenBoxes is a free, open-source supply chain management platform built for healthcare and humanitarian logistics. It provides inventory tracking, demand forecasting, order fulfillment, and shipment management across multiple facilities.

This 1-Click App deploys a fully configured OpenBoxes instance running on Apache Tomcat 9, with MySQL, Nginx reverse proxy, and firewall pre-configured. On first boot, unique database passwords are generated automatically and saved to /root/.digitalocean_password. The default web login is admin/password (change immediately).

Optional domain and SSL setup is available via an included script: /opt/openboxes/setup-domain.sh

Software Included

Creating an App using the Control Panel

Click the Deploy to DigitalOcean button to create a Droplet based on this 1-Click App. If you aren’t logged in, this link will prompt you to log in with your DigitalOcean account.

Creating an App using the API

In addition to creating a Droplet from the OpenBoxes Server 1-Click App using the control panel, you can also use the DigitalOcean API. As an example, to create a 4GB OpenBoxes Server Droplet in the SFO2 region, you can use the following curl command. You need to either save your API access token to an environment variable or substitute it in the command below.

curl -X POST -H 'Content-Type: application/json' \
         -H 'Authorization: Bearer '$TOKEN'' -d \
        '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"openboxes-openboxesserver"}' \
        "https://api.digitalocean.com/v2/droplets"

Getting Started After Deploying OpenBoxes Server

Getting Started Instructions

1. Connect to your droplet via SSH

ssh root@your_droplet_public_ipv4

The login banner displays your app URL, credentials location, and useful commands.

2. Wait for initialization

OpenBoxes takes 3–5 minutes to start on first boot. You will see a “starting up” page in your browser until it is ready.

Watch startup progress:

tail -f /opt/tomcat9/logs/catalina.out

Look for Started Application in X seconds to confirm it is ready.

3. Log in

Open http://your_droplet_public_ipv4/openboxes in your browser.

• Username: admin
• Password: password

Change this password immediately after first login.

4. View credentials

Database passwords are generated automatically on first boot:

cat /root/.digitalocean_password

5. Set up a domain with SSL (optional)

Point your domain’s DNS A record to the droplet IP, then run:

/opt/openboxes/setup-domain.sh

This configures Nginx with your domain, obtains a Let’s Encrypt SSL certificate, and enables automatic HTTPS redirect.

Check service status

systemctl status tomcat9 mysql nginx

Upgrading

Keep an eye out for new releases:

• Releases
• Announcements

NOTE: Back up your database or take a snapshot before upgrading.

Troubleshooting

“OpenBoxes is starting up” page (502)

This is normal. OpenBoxes takes 3–5 minutes to start after first boot or a restart. The page auto-refreshes every 15 seconds.

Check startup progress:

tail -f /opt/tomcat9/logs/catalina.out

Look for Started Application in X seconds to confirm it’s ready. If the service keeps restarting, check for errors:

grep -E "ERROR|Exception" /opt/tomcat9/logs/catalina.out | tail -20

Common causes of repeated restarts:

• Out of memory — use free -m to check. The app needs ~1.5 GB. Use a droplet with at least 4 GB RAM.
• MySQL not running — verify with systemctl status mysql. If it’s down, start it: systemctl start mysql.
• Grails config error — check /opt/openboxes/.grails/openboxes.yml for syntax issues.
• Tomcat not running — verify with systemctl status tomcat9. Restart with systemctl restart tomcat9.

DNS propagation delays

After creating a DNS A record, it can take anywhere from a few minutes to 48 hours to propagate, though most providers complete within 5–15 minutes.

Check if your record has propagated:

dig yourdomain.com +short

This should return your droplet’s IP. If it returns nothing or the wrong IP:

• Verify the A record is correct in your DNS provider’s dashboard.
• Try a different DNS resolver: dig @8.8.8.8 yourdomain.com +short
• Lower the TTL on your DNS record if you anticipate changes.
• Wait and try again — some registrars are slower than others.

Do not run setup-domain.sh until DNS is resolving correctly. Certbot will fail to issue a certificate if it can’t reach your domain.

Certbot / SSL certificate issues

“Challenge failed” or “Connection refused”:

• DNS hasn’t propagated yet. Verify with dig (see above).
• Port 80 is blocked. Verify: ufw status should show 80/tcp ALLOW.
• Another process is using port 80. Check: ss -tlnp | grep :80

“Too many failed authorizations” (rate limit):

• Let’s Encrypt limits failed attempts. Wait 1 hour and try again.
• Test with staging first: edit setup-domain.sh and add --staging to the certbot command, then re-run. Remove --staging for the real certificate.

Certificate renewal:

Certbot installs a systemd timer that auto-renews certificates. Test it with:

certbot renew --dry-run

The setup script is safe to re-run after a failure. It will overwrite the Nginx config and request a new certificate.

Logs reference

Useful Links

Support Contact

If you encounter any issues or would like to leave feedback, please join our community support forum:

https://community.openboxes.com