122 lines
4.8 KiB
ReStructuredText
122 lines
4.8 KiB
ReStructuredText
|
|
.. highlight:: sh
|
|
|
|
Virtual Environment
|
|
===================
|
|
|
|
Regardless of platform, you are strongly encouraged to use a `virtual
|
|
environment`_ for your app. This allows you to experiment with installation
|
|
without affecting the rest of your system.
|
|
|
|
.. _virtual environment: https://packaging.python.org/glossary/#term-Virtual-Environment
|
|
|
|
|
|
Choosing a Location
|
|
-------------------
|
|
|
|
It can be helpful to standardize the location of all virtual environments
|
|
regardless of their purpose. The tool you use to create a virtual environment
|
|
may (or may not) have opinions on that, but so do we:
|
|
|
|
This manual will assume one of the following based on platform:
|
|
|
|
* Linux - ``/srv/envs``
|
|
* Windows - ``C:\envs``
|
|
|
|
So for instance if you run Linux and make a new virtual environment named
|
|
"poser" then it would live in ``/srv/envs/poser`` according to the above.
|
|
|
|
Note that you may need to consider file permissions etc. when choosing your
|
|
actual location, but if possible you're encouraged to use the examples shown
|
|
here.
|
|
|
|
|
|
Choosing a User
|
|
---------------
|
|
|
|
To be thorough you may need to consider which user should "own" the virtual
|
|
environment and installed app. If you're just getting started then you can
|
|
skip this section for now and run all commands as yourself, then revisit the
|
|
issue later as needed.
|
|
|
|
Why the User Matters
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The virtual environment and installed app, its config and data files etc. must
|
|
be owned by someone after all. So at the most basic level the user matters
|
|
simply because it can't be "nobody" - a choice must be made.
|
|
|
|
Some config, data and/or log files may contain sensitive information (passwords
|
|
etc.) and should be "locked down" in some way to prevent unauthorized access.
|
|
So then the "owner" would have access to such files but perhaps no other users
|
|
would.
|
|
|
|
When app commands are ran, by yourself in the console or e.g. via cron job, the
|
|
user which the command "runs as" will matter, in the sense that this user will
|
|
need access to any "restricted" (e.g. config) files. So typically all commands
|
|
would be ran as the same user who "owns" the app.
|
|
|
|
User Options
|
|
^^^^^^^^^^^^
|
|
|
|
**"yourself"** - For instance my own username is 'lance' and so for convenience
|
|
in development, I might just run all commands as myself, and let all files be
|
|
owned by myself. This is the simplest option and most commands in this manual
|
|
will work as-is for this option.
|
|
|
|
**"root"** - When deploying the app to a server, maybe I am connecting to it
|
|
via SSH as the 'lance' user, but let's say I am just one of several users who
|
|
needs to connect, and so it doesn't make for 'lance' to be the file owner, or
|
|
to run app commands as 'lance'. You can, if you really want to, use 'root' as
|
|
the app owner/user, although you are encouraged to use one of the other options
|
|
below instead.
|
|
|
|
**"admin"** - In some organizations there is a dedicated "admin" user defined
|
|
within LDAP etc. If such a user is already present in the system then there
|
|
may be no reason not to use this for the app owner/user.
|
|
|
|
**"rattail"** - This option is my personal preference. Here we create a
|
|
dedicated system user whose sole purpose is to be the app owner/user. I always
|
|
name this user 'rattail' and you can think of it like the 'www-data' or
|
|
'postgres' user accounts. Basically this is a "true" system user meaning it
|
|
doesn't correspond to any person. But it can be defined on many machines for
|
|
automation's sake, e.g. if SSH keys are shared too then 'rattail' user on one
|
|
machine can effectively run 'rattail' commands on any other machine.
|
|
|
|
|
|
Creating a Virtual Environment
|
|
------------------------------
|
|
|
|
Please also see `Creating a virtual environment`_ in the Python Packaging User
|
|
Guide.
|
|
|
|
.. _Creating a virtual environment: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
|
|
|
|
For our purposes, on Linux you can do this::
|
|
|
|
python3 -m venv /srv/envs/poser
|
|
|
|
|
|
Using a Virtual Environment
|
|
---------------------------
|
|
|
|
If you're new to virtual environments then you're encouraged to read over the
|
|
following, from the Python Packaging User Guide:
|
|
|
|
* `Activating a virtual environment <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment>`_
|
|
* `Leaving the virtual environment <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#leaving-the-virtual-environment>`_
|
|
|
|
So for our Linux example you might activate with::
|
|
|
|
source /srv/envs/poser/bin/activate
|
|
|
|
*All* commands in this manual will assume you have a virtual environment, but
|
|
*most* of them will not require it to be "activated" to run the command. The
|
|
main exception to that is ``pip`` commands, which *do* assume the virtual
|
|
environment is activated.
|
|
|
|
It may be helpful to ensure your new virtual environment has the lastest pip
|
|
and friends. Note that your env should be activated when running this::
|
|
|
|
pip install -U pip setuptools wheel
|