Edit This Page

Managing Storage and Cleanup

Repsy Open Source stores package files on the local file system, in the directory you set with STORAGE_BASE_PATH. This page describes how that directory is laid out, what happens to a file when you delete something, which background jobs clean up, and how to plan disk space. For backups, see Persisting Data and Backups.

The examples assume STORAGE_BASE_PATH=/app/data/storage, the value used everywhere in this documentation.

The storage layout

Each package format has its own directory inside the storage directory. Below it, every repository has a folder named after the repository’s internal id (a UUID), not after its name, so a repository keeps its folder when you rename it:

/app/data/storage
├── maven/
│   ├── 01a0d860-a8d5-7e69-961f-212c40565d93/   files of one Maven repository
│   └── trash/                                  deleted Maven files, see below
├── npm/
├── pypi/
├── docker/
├── cargo/
├── golang/
├── helm/
├── nuget/
└── ruby/

To find out which folder belongs to which repository, ask the database:

SELECT id, name, type FROM repo;

Inside a repository folder, the files are arranged by format:

The layout is an internal detail. Read it, back it up, and measure it, but do not add, edit or move files inside it: the database knows which files it expects, and it may change between releases. While Repsy writes a file, it first writes a hidden temporary file named .repsy-write-<id>.tmp next to the target and then moves it into place, so a download never sees a half-written file. The trash job (see below) removes such files if a crash left them behind and they are a day old.

To see how much space each format uses, or how much the trash holds:

docker exec repsy sh -c 'du -sh /app/data/storage/*'
docker exec repsy sh -c 'du -sh /app/data/storage/*/trash'

The Repository Storage section in the settings of a repository in the web UI shows the disk space of that repository.

The trash

Deleting something in Repsy does not delete its files at once. Repsy removes the database records and moves the files into a trash directory inside the directory of their format:

/app/data/storage/<format>/trash/<date>/<timestamp>/<original path>

For example, deleting a Maven version puts its files under maven/trash/2026-10-01/2026-10-01T09:30:12.263957118Z/<repository id>/com/example/demo/1.0/. What goes to the trash:

Repsy keeps the files for a while, so an operator can still copy them out. It also means that deleted files keep using disk space until the trash is emptied.

Emptying the trash

A background job empties the trash. It deletes the date directories that are older than the retention period:

• The default retention is seven days. Raise it to keep deleted files for longer, for example TRASH_RETENTION=P30D.
• A value below P1D is refused and Repsy does not start, because the trash is grouped by day.
• The trash is kept in one directory per day, so the job works in whole days: it removes a day once that whole day is older than the retention period.
• The first run after an upgrade deletes the whole backlog. Releases before the one this documentation describes moved deleted files into the trash but never emptied it. If you upgrade such an instance, the first run of the job (15 minutes after start) permanently removes everything that is older than TRASH_RETENTION. Copy the trash away first, or set TRASH_CLEANUP_ENABLED=false for the upgrade, if you want to keep it. See Upgrading Repsy Open Source.

By default Repsy logs at WARN level, so you do not see the job report. To see it, run Repsy with LOGGING_LEVEL_IO_REPSY=INFO. Each format then reports a line such as cleared MAVEN storage trash: 3 directories, 1 files, 3 bytes freed.

Other cleanup jobs

Repsy never deletes a package or a version by itself. The only things it removes on its own are the following.

All durations are ISO-8601 durations: PT15M is fifteen minutes, PT24H is twenty-four hours and P7D is seven days.

• Abandoned uploads. An upload counts as abandoned when its file has not been written to for the TTL, so an upload that is still receiving data is left alone. The files are moved to the trash like any other deletion, and the space is released from the usage of the repository.
• Held Maven signatures. A Maven repository that verifies every signature accepts a signature file before the file it signs, because Maven uploads in parallel. Repsy holds the signature, unverified and not served, until the file arrives. Held signatures are kept in the database, not on disk, and the job deletes those older than the TTL.
• Docker manifest layout repair. Ten minutes after the first start following an upgrade from a 26.08 release, a background job renames the stored Docker manifests. It is safe to leave alone: until a manifest has been renamed, Repsy serves it from its old name. See Upgrading Repsy Open Source.

Upload size limits

Some protocols have a size limit for a single upload. A larger upload is refused with 413 and the message “The uploaded content is too large.” Each limit is a variable that accepts a size such as 100MB or 1GB:

Repsy has no size setting for the other formats, such as Maven, npm and Docker layers. A reverse proxy in front of Repsy can have its own limit, see Running Behind a Reverse Proxy.

Disk space

Plan disk space for four things:

• The storage directory. It grows with what you publish. The web UI shows the disk usage of each repository. Docker layers are stored under their digest.
• The trash. Deleted files stay for TRASH_RETENTION days. If you delete a lot, for example a whole repository, expect the disk usage to stay the same until the retention has passed. Lower the retention (not below one day) if disk space is short, or empty it with the job settings above.
• Temporary space for uploads. Repsy copies most uploads into a temporary file while it checks them, then stores them, so that a package of any size is never held in memory. That file lives in the temporary directory of the Java process, which is /tmp in the image and so in the writable layer of the container. It has to hold your largest upload, and several uploads at once. Give the container enough space there, for example by mounting a volume on /tmp. Repsy removes these files when the request ends.
• The database. It holds metadata only and is small compared with the package files.

If the disk fills up, uploads fail, and a failed write leaves the previous content of a file unchanged: Repsy writes to a temporary file and moves it into place only when the whole upload has arrived. Free space, and the uploads that failed can be repeated.

Do not forget the space for backups, which need a full copy of the database and the storage directory.

Persisting Data and Backups Upgrading Repsy Open Source

Was this page helpful?

Yes No