The best way to run Parcel is with Docker. You can find the Docker image on both Docker Hub and the GitHub Container Registry:
To try out Parcel, you can run Parcel in a Docker container with the following command:
docker run -p 3000:3000 blakerain/parcel
By default, Parcel will run on port 3000. We tell Docker to map port 3000 on the host to port 3000
in the container with the -p 3000:3000 argument. This allows you to access Parcel from your host
machine. You can access it in your browser at http://localhost:3000.
When you browse to http://localhost:3000, you will see the Parcel welcome page, asking you to
create the first administrator user.
/images/admin-initial-setup.png
You can read more about the initial setup on the first time setup wiki page.
Environment Variables
Parcel can be controlled through arguments or environment variables. The environment variables are a useful way to control Parcel when creating a Docker container.
There are three envronment variables that are most commonly used to configure Parcel:
| Environment Name | Default | Description |
|---|---|---|
DB |
sqlite://parcel.db |
SQLite connection string |
CACHE_DIR |
./cache |
Directory for file cache |
COOKIE_SECRET |
Secret used for session cookie encryption |
Setting the Database
The DB environment variable is used to set the SQLite database connection string. By default,
Parcel will use an SQLite database file named parcel.db in the root director of the container.
This is not recommended for production use, as it means the database will be lost when the container
is removed. Instead, you should use a persistent volume or a different database system.
The connection string can be set to any valid SQLite connection string. For example, to use a persistent volume for the database, you can create a new Docker volume and then use it with the container.
docker volume create parcel_data
docker run \
-p 3000:3000 \
-v parcel_data:/data \
-e DB=sqlite:///data/parcel.db \
blakerain/parcel
This command uses the -v flag to bind a Docker volume named parcel_data to the /data directory
in the container. The DB environment variable is set to store the SQLite database in this
directory. This way, the database will persist in the parcel_data volume, even if the container is
removed.
Setting the Cache Directory
Alongside the database, Parcel also uses a "cache" directory where it stores the uploaded files.
Just like the database, you can use a Docker volume to persist the cache directory. By default,
Parcel will use a directory named cache in the root of the container. You can change this by
setting the CACHE_DIR environment variable.
Here we're going to use the same parcel_data volume we created for the database to store the cache
directory as well:
docker run \
-p 3000:3000 \
-v parcel_data:/data \
-e DB=sqlite:///data/parcel.db \
-e CACHE_DIR=/data/cache \
blakerain/parcel
Setting the Cookie Secret
Parcel uses a cookie to store the session information. This cookie is encrypted using a secret
key. By default, Parcel will generate a random secret key when it starts up. However, for
production use, it is recommended to set a fixed secret key using the COOKIE_SECRET environment
variable. This ensures that the session cookies remain valid even if the container is restarted.
The COOKIE_SECRET environment variable should be set to a base-64 encoded string of 32 bytes of
random data. This can be generated very easily using the openssl command:
openssl rand -base64 32
You can then set the COOKIE_SECRET environment variable when starting the Docker container:
docker run \
-p 3000:3000 \
-v parcel_data:/data \
-e DB=sqlite:///data/parcel.db \
-e CACHE_DIR=/data/cache \
-e COOKIE_SECRET=$(openssl rand -base64 32 | tr -d '\n' ; echo) \
blakerain/parcel