agobackup

Backup and restore for ArcGIS Online. Self-hosted, open source, one container.

ArcGIS Online has no org-level backup. Esri's own guidance is that protecting your content is your job, and the only native safety net is an opt-in recycle bin that keeps deleted items for 14 days, after which they are gone permanently. The tools that fill this gap today start around $600 to $1,200 a year per organization, and one of them keeps your backups on the vendor's cloud.

agobackup is the free option: point it at your organization, tell it what to copy and how often, and it writes snapshots to a disk you control or any S3-compatible bucket.

Status: early. Backup, scheduling, retention, verification and restore all work and are tested. It has not yet been run in anger by anyone but its author, so don't make it your only backup quite yet.

What it does

• Feature layer data exported as File Geodatabase, with attachments, domains and relationship classes included, plus a /query to GeoJSON fallback for view layers and items the connected account doesn't own.
• Item definitions for everything else: web maps, dashboards, Experience Builder apps, Survey123 forms, plus resources, thumbnails, sharing state and related-item relationships. These are small, so every snapshot keeps a full copy and you get a browsable history.
• Scheduling built into the app, with cron expressions and real timezones. No host crontab, no scripts to babysit.
• Retention using grandfather-father-son rules with the same semantics as restic and borg, described in plain English rather than bucket arithmetic, and with a preview naming exactly which backups pruning would delete and why.
• An activity log that outlives what it describes. Every other record in a backup tool dies with the backup it belongs to, which is precisely the moment you need it. Snapshot created, finished, deleted, and by what: you, the schedule, retention, cleanup. Nothing on that page is ever deleted, so "where did my backup go?" always has an answer.
• Every backup is a full backup. Restore from any of them and you get everything as it was at that moment, with no chain of differentials to replay, and deleting an old backup can never damage a newer one. Layers that haven't been edited aren't downloaded again; on local storage they're hard-linked, so they cost no extra disk while remaining real files.
• Change detection that actually works. ArcGIS Online does not update an item's timestamp when its features are edited. Measured on a real org, four of eight layers had data edited months after their item last "changed". agobackup reads each layer's true last-edit date instead, and re-exports whenever it can't be sure.
• Verification, which most backup tools skip: every snapshot records SHA-256 digests and source feature counts, and can be re-checked on demand or in rotating subsets to keep object-storage egress down.
• Healthcheck pings to healthchecks.io or Uptime Kuma, so you find out when backups quietly stop running.
• Restore, from the browser. Download any file from a backup, or put it back: into the existing layer (keeping its item ID and service URL, so nothing that points at it breaks), over a web map or app whose configuration got wrecked, or as a new item. Dry run is the default, so you see exactly what would change before anything does, and every restore is recorded.
• Reference rewiring, the thing the paid tools call "rewiring". Restoring as a new item means a new item ID, so agobackup finds every map and app that pointed at the original and offers to repoint them, both the item references and the hard-coded service URLs web maps keep alongside them.

Quick start

You need Docker Desktop (or Docker Engine on a server) and nothing else. These commands are the same on Windows, macOS and Linux.

1. Get the files.

git clone https://github.com/palavido-dev/agobackup.git
cd agobackup

2. Create your settings file. .env.example is a template; copying it gives you a .env to edit.

cp .env.example .env

On Windows, copy .env.example .env in Command Prompt does the same thing.

3. Set a password. Open .env in any text editor and change AGOBACKUP_ADMIN_PASSWORD to something only you know. That is the password you will sign in with. Everything else in the file has a working default, so you can leave it alone.

4. Start it.

docker compose up -d

That pulls a published image (ghcr.io/palavido-dev/agobackup, amd64 and arm64) and starts it in the background. To build from source instead:

cp docker-compose.override.yml.example docker-compose.override.yml
docker compose up -d --build

5. Open http://localhost:8000 and sign in as admin with the password you set. Then:

1. Organizations: connect your ArcGIS Online org and test the connection.
2. Storage: confirm the local target, or add an S3 bucket.
3. Plans: create a plan, pick what to back up, set a schedule, save.
4. Run now: watch the log stream, then check the snapshot.

There is no encryption key to generate. The first time agobackup starts it creates a random one for itself and keeps it in the data folder, as data/secret.key. It encrypts the ArcGIS password you type into the Organizations page, so keep that folder: without it those saved passwords cannot be read back, and you would have to enter them again. If you would rather hold the key somewhere else, set AGOBACKUP_SECRET_KEY in .env and agobackup will use yours and never write a file.

Without Docker

pip install -e ".[dev]"
cp .env.example .env      # edit it
agobackup serve

The account you connect matters

ArcGIS Online restricts the portal export operation to an item's owner or a member of the default administrator role. Custom roles carrying admin-looking privileges are refused, and API key credentials cannot hold admin privileges at all, which is why agobackup asks for a username and password rather than a token. Create a dedicated service account with the default administrator role.

Accounts that sign in through SAML/enterprise identity or with enforced MFA cannot be used for unattended backups. That is an ArcGIS Online constraint, not one this tool can work around.

Credentials are encrypted at rest with the key described in the quick start. Changing that key makes previously stored credentials unreadable, so if you move an installation, move the data folder with it.

Things worth knowing before you rely on any AGO backup

• Item IDs can never be preserved. ArcGIS Online mints a new ID on every upload; only ArcGIS Enterprise honours preserve_item_id. Any restore that creates a new item breaks the web maps and apps that referenced the old one, unless those references are rewritten. In-place overwrite keeps the ID and the service URL and is the mode to prefer.
• Exports cost storage credits until they're deleted. The portal export operation creates a temporary item in your org. agobackup deletes it in a finally block, always, and logs loudly if the cleanup fails.
• The API quota is org-wide, undocumented and shared with every other request hitting your organization, including anonymous traffic on public layers. agobackup paces itself and backs off on quota errors rather than hammering.
• Exports and queries themselves cost no credits. Storage does.
• On ArcGIS Enterprise, a backup tool can take your server down. Hitting the REST endpoint of a service wakes an ArcSOC process for it; do that across a thousand registered services and the site falls over. agobackup detects Enterprise portals, paces itself to one item at a time, and does not read data from services running on your own ArcGIS Server unless you explicitly ask it to.

Repository layout

A snapshot on disk or in a bucket looks like this. They are plain files you can read without agobackup running, in folders named after your organization and plan rather than internal ids. The date and time are in the plan's own timezone:

riverside/nightly-everything/2026-07-27_0200-41/
  manifest.json                      # items, digests, feature counts, totals
  items/<itemId>/
    item.json                        # portal item description
    data.json                        # web map / dashboard / app definition
    sharing.json                     # access level, groups, folder
    related.json                     # Survey2Service and friends
    resources/...                      # app config, custom styles
    thumbnail/...
    data/data.gdb.zip                # feature layer export

Architecture

Python throughout: FastAPI, SQLAlchemy, APScheduler, SQLite, Jinja templates and one vendored copy of htmx. No Node build step, no Redis, no Celery, no arcgis package. One container, two volumes, one language for contributors to learn. See docs/ARCHITECTURE.md.

Documentation

• docs/ARCHITECTURE.md: how it's put together and why
• docs/ROADMAP.md: what's next, and what's deliberately out of scope

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md. Tests: pytest. Lint: ruff check .. The suite needs no ArcGIS account: portal responses are mocked, and a full backup and restore run end to end against a fake portal.

Security policy and an honest list of the current gaps: SECURITY.md.

License

AGPL-3.0-or-later. You can run this, modify it and self-host it freely. If you offer it to others as a hosted service, your changes have to be published too. See LICENSE.