.. 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 `_ * `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