Upgrade from v0.6.x to v0.7.0
MediaLit v0.7.0 streams uploads from the client straight into your private bucket as S3 multipart uploads, instead of writing them to the server's disk first. Big uploads no longer need disk space on the server, and a resumable upload can continue on any API instance.
Because the parts of an unfinished upload now live in your bucket, the bucket needs a lifecycle rule that removes them if MediaLit doesn't. Add it before you upgrade.
What changes
Uploads no longer use the server's disk.
TEMP_FILE_DIR_FOR_UPLOADSis now only a working folder for thumbnails and WebP conversion.Unfinished uploads are kept in your bucket until they finish or are aborted. MediaLit aborts them when they expire, and the bucket's lifecycle rule catches any it misses.
Resumable uploads must declare their size when they start.
@medialit/uploader,@medialit/react, the CLI andtus-js-clientwith a known file size already do. A tus client that defers the length gets a 400 withUpload-Length is required.Requests no longer time out after five minutes. A connection is closed only after
REQUEST_IDLE_TIMEOUT_MS(2 minutes) with no data, so big uploads on slow links can finish.Regular uploads are capped per API process by
MAX_CONCURRENT_FORM_UPLOADS(16). Over the cap, the API answers 503 with aRetry-Afterheader.An upload counts toward storage from the moment it starts. If the server crashes mid-upload, the upload is cleaned up and its storage freed after
UPLOAD_STALE_MINUTES(30).
All the new settings are optional and have defaults. See Tune upload streaming.
1. Back up the database
With the bundled PostgreSQL service:
docker compose exec -T postgres pg_dump -U medialit medialit > medialit-before-0.7.0.sqlThe migrations add a column to media and remove two columns from tus_uploads. Migrations can't be rolled back, so a backup is the only way back to v0.6.x.
2. Add the lifecycle rule to your private bucket
On AWS S3, add a rule that aborts incomplete multipart uploads 7 days after they start. The commands are in Clean up unfinished uploads. Check the bucket's existing rules first, because applying a lifecycle configuration replaces them.
Cloudflare R2 buckets already have such a rule, and MinIO, including the bundled one in Docker Compose, cleans up unfinished uploads on its own. If you use either, check that the rule or setting is still in place and go to step 3.
3. Let resumable uploads finish
Resumable uploads in progress during the upgrade can't be resumed afterwards, because their parts are on the old server's disk. Clients that try get a 404 and start the upload again from the beginning. If you can, upgrade when few uploads are running.
4. Upgrade
docker compose pull
docker compose up -dThe init service runs the migrations before the API starts. If you run the image without Docker Compose, run bun apps/api/src/db/migrate.ts with the new image before starting the API.
5. Check it worked
Upload a file, for example with the CLI:
medialit upload ./photo.png --endpoint https://medialit.example.com. It should print the file's URL.Upload something big enough to take a few seconds, then press Ctrl+C halfway. On AWS S3,
aws s3api list-multipart-uploads --bucket your_private_bucket_nameshows that upload's parts until MediaLit or the lifecycle rule aborts it. A regular upload is aborted withinUPLOAD_STALE_MINUTES. A resumable upload is kept until it expires, so the client can still finish it.If you serve videos, upload a short video and check that it gets a thumbnail. MediaLit now makes video thumbnails by reading the video from the bucket through
CLOUD_ENDPOINT, so the API must be able to reach that address.
