User Guide — Terrarium 1.0.1 documentation

# User Guide

    terrarium [options] COMMAND [requirements files...]

See `terrarium --help` for a complete list of options and commands.

## Creating a new environment

The following example will create a new virtual environment named `env` that includes the packages defined in `requirements.txt`

    $ terrarium --target env install requirements.txt

## Replacing an existing environment

The following example demonstrates how terrarium can be used to replace an existing activated virtual environment with a different set of packages.

    $ terrarium --target env install requirements.txt
    $ source env/bin/activate
    $ terrarium install other_requirements.txt

Note

The environment that was replaced is renamed to `env.bak`, and can be restored using `terrarium revert`.

Note

After installing the `other_requirements`, it is not necessary to run `deactivate` or `activate` to begin using the new environment.

## Saving and using environment archives

Terrarium provides options for archiving and compressing a freshly installed and built environment, either locally or remotely (via Amazon S3).

When these options are used, terrarium will first check if the environment has already been saved. In that case, terrarium will download the environment archive instead of downloading and building each individual package specified in the requirements files.

### Storing terrarium environments locally

Storing terrarium environments locally (or on a shared network disk) can be achieved using the `--storage-dir` option.

    $ terrarium --target env --storage-dir path/to/environments install requirements.txt

After building a fresh environment from the requirements in `requirements.txt`, terrarium will archive and compress the environment. Finally, the compressed version is then copied to the path specified by `--storage-dir`.

### Storing terrarium environments on Cloud Storage Services (S3, GCS)

Terrarium also supports storing and retrieving archives stored on these storage services:

> - Amazon Web Service - S3
> - Google Cloud Platform - Google Cloud Storage

#### Amazon S3

The following options are only available if `boto` is installed.

> - `--s3-bucket`
> - `--s3-access-key`
> - `--s3-secret-key`
> - `--s3-max-retries`

#### Google Cloud Storage

The following options are only available if `gcloud` is installed.

> - `--gcs-bucket`
> - `--gcs-client-email`
> - `--gcs-secret-key`
> - `--gcs-max-retries`

Note

Each of the above options can be specified using environment variables, e.g. `S3_BUCKET`, `GCS_BUCKET` instead of being passed in as a parameter.

## Tips

### Using an alternative index server

If you’re using an index server other than PyPI (perhaps an index server with internal-only packages), then you need to be able to tell terrarium to use that index URL. Terrarium does not have the `-i` (`--index-url`) option that pip has, so how do you indicate the index URL? Well, you may recall that pip requirements files can also contain command-line options… So add a line like this to one of your requirements files:

    --index-url http://internal-index-server.corp/index

You can add a line like the above to an existing requirements file that has a list of packages or you could add it to a separate requirements file and then add that to the terrarium command-line.

    $ terrarium --target testenv install internal-index-server.txt requirements.txt