Skip to main content

atomically deploy your code from tarballs

Project description

tarball-deploy - atomically deploy your code from tarballs

Build status PyPI page Code style: black

tarball-deploy is an utility to facilitate deploying code (or any files, for that matter) packed into TAR archives. It handles unpacking received archives, and switching to new releases atomically (using a little bit of symlink magic).

Use cases

tarball-deploy has been written with shared web hosting services in mind, which usually grant you SSH access to a shared server, and one or more public_html directories, where you're expected to put your website files (eg. static HTML, or PHP scripts). This tool attempts to address the following problems:

  • How to copy new release of your website from your CI/CD pipeline (you have one, right?) to your server.
  • How to switch to the new release atomically, so that the site is in consistent state all the time.
  • How to call securely additional hooks before and after deployment (f.ex. restarting your web server), in a way which does not allow your CI runner to execute arbitrary commands on the server.


  • A decent UNIX-like system, which will let you install custom Python scripts
  • A tar implementation. GNU Tar and libarchive (FreeBSD) tar are known to work.


Remember that tarball-deploy is expected to be installed on your server. The easiest way is to install it with pip:

$ pip install tarball-deploy

You might, however, want or need to install it in a virtualenv and symlink somewhere in your $PATH.


To use tarball-deploy, you need to pack your code into a TAR archive first. This is out of scope of this project, but usually you can do something like:

$ tar cf release.tar index.html style.css images/**

Then you can proceed with your preferred deployment method from below.

Deploy from local machine

$ ssh your-username@your-host tarball-deploy --workdir=/your/remote/deployment/dir < release.tar

Should things go wrong, you can quickly revert to the previous deployment:

$ ssh your-username@your-host tarball-deploy --workdir=/your/remote/deployment/dir --rollback

Deploy from CI

For every website you want to manage, you will need to:

  • Generate an SSH keypair for your CI runner
  • Edit .ssh/authorized_keys on your server and add something similar to:
    restrict,command="tarball-deploy --workdir=/your/remote/deployment/dir" ssh-rsa AAAAB3Nza...
  • Symlink /your/remote/deployment/dir/current to a place where your web server is expected to find your site content (usually something like ~/domains/

Calling additional hooks

Put your pre-deploy and post-deploy scripts inside /your/remote/deployment/dir/hooks. They need to be marked as executable.


Created by Piotr Śliwka



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tarball-deploy, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size tarball-deploy-0.1.0.tar.gz (6.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page