Pipenv: [docs] Simple steps for service deployment

[lofidevops]

User story: I am a Django developer. I want to deploy my Django site onto a Debian server machine, so that I can execute it as a daemon/service.

Problem: The advanced docs currently mention --system --deploy but don't explain what they do: https://pipenv.readthedocs.io/en/latest/advanced/#deploying-system-dependencies

(This issue is an attempt to isolate one item from https://github.com/pypa/pipenv/issues/2660 , define a clear user story to be addressed, and document the solution.)

[lofidevops]

To clarify, I'm intending to write this documentation. Please point me to the relevant location (I assume a new section on the "Advanced" page?)

[techalchemy]

It seems plausible that this is not in the documentation!

[lofidevops]

--deploy seems self-explanatory (Abort if the Pipfile.lock is out-of-date, or Python version is wrong.) I can expand on this.

[lofidevops]

--system just says "System pip management." This is less clear to me. What does it mean?

1. Will I be installing packages to a system location rather than a local virtualenv folder? If so, I probably need sudo?

2. Will I be using the system default Python + pip rather than a new pip in the virtualenv?

If there is an equivalent virtualenv and/or pip command, please let me know, thanks!

[lofidevops]

If I:

• pip install with a combination of --system and/or --deploy
• AND, I have a requirements.txt in my root folder

...will I reimport the requirements.txt? I still have it for legacy reasons, but I don't want it to interfere with my pipenv-driven deployment.

[wmorrell]

Some comments on what I believe pipenv is doing around this subject, from a person relatively new to pipenv and using it in a Django and Docker workflow. Caveats apply to all the below, please get additional confirmation from others more familiar with the project before treating as True.

pipenv install --system instructs pipenv to use the system Python site-packages, rather than the default behavior of creating a new virtualenv with its own site-packages. This is especially preferable in a Docker deployment, to avoid any complications getting the correct Python environment set up, and in minimal containers there should not be any issues with other processes running that might get screwed up if existing packages get clobbered. The need for sudo depends on permissions for the site-packages directory. I have not required it so far, using on macOS and Debian systems, in addition to Docker, but YMMV.

The requirements.txt is not considered at all when using --system or --deploy. The former is instructing pipenv where the target site-packages will be, and which binaries to use; the latter is instructing pipenv to use the pinned versions in Pipfile.lock rather than attempting to run package version resolution from the version specifiers in Pipfile. Using --deploy should abort if the hash computed from Pipfile does not match the hash included in Pipfile.lock. You would use --deploy when your intention is to exactly replicate a deployment specified by the lock file; you would drop the --deploy when your intention is to create an environment that satisfies the version specifiers in Pipfile, and doing so implies the creation of a new Pipfile.lock.

[sirosen]

There appear to be at least three ways of doing a reproducible install from the lockfile. Which of these is recommended, and why?

• pipenv install --ignore-pipfile
• pipenv install --deploy
• pipenv sync

I've been using pipenv install --ignore-pipfile, which seems to do what I want.

We don't want things to fail if we go back to an old commit and Pipfile.lock _could_ be updated -- we went back to that commit on purpose, and used an old Pipfile.lock on purpose.
We also don't want things to fail if there's a delay between Pipfile.lock being committed and a build happening. If a library updates at the same time that an app version is making its way through a CD pipeline, that should be ignored/okay.

It seems like pipenv install --deploy won't work for these cases, unless I misunderstand?

What exactly is the difference between pipenv install --ignore-pipfile and pipenv sync?
I think any docs about deployment should cover that too.

[techalchemy]

Hey, sorry for the delay here! It's been a crazy few weeks. Firstly thanks for starting this very necessary discussion and tackling this documentation problem!

@kwill :

--system just says "System pip management." This is less clear to me. What does it mean?

It just means we use which pip to find pip and invoke it directly, basically, instead of making a virtualenv (so often this is derived from python -m pip or else it is found on your path). It means that installation is done without any resolution and without any virtualenv creation.

pip(env[sic]) install with a combination of --system and/or --deploy
AND, I have a requirements.txt in my root folder

...will I reimport the requirements.txt? I still have it for legacy reasons, but I don't want it to interfere with my pipenv-driven deployment.

If you have a pipfile or a lockfile, pipenv should skip your requirements file if it finds one. If you use --deploy pipenv should never use anything but your lockfile and will fail spectacularly if the lockfile and pipfile do not agree with one another (the lockfile stores a hash of the pipfile used to generate it)

---

@sirosen

There appear to be at least three ways of doing a reproducible install from the lockfile. Which of these is recommended, and why?

pipenv install --ignore-pipfile

This installs dependencies from your Pipfile.lock only, whether you have a pipfile or not, whether it is out of sync with your lockfile or not, it doesn't even check.

pipenv install --deploy

This command is an 'enforcement' command, it basically says 'install the dependencies from my lockfile, if and only if my lockfile is in sync with my pipfile, otherwise give me an error message'.

pipenv sync

This command says 'take the dependencies specified in my lockfile and put them in my virtualenv'

[lofidevops]

@sirosen Thanks! This doesn't answer "how exactly do I deploy a Django app with pipenv" but it does effectively resolve the ambiguity in the docs, so I think this issue is resolved.