mirror/weewx
1
0
Fork 0
mirror of https://github.com/weewx/weewx.git synced 2026-04-18 00:26:57 -04:00
Code Issues Packages Projects Releases Wiki Activity

make git and pip pages consistent

Browse Source
This commit is contained in:
Matthew Wall
2023-07-17 09:28:04 -04:00
parent 7b7f17ef1d
commit d174a0debc
2 changed files with 176 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs_src/quickstarts/git.md
View File

@@ -1,37 +1,27 @@
# Running WeeWX from a git repository
Because WeeWX is pure-Python and does not need to be compiled, it can be run directly from a source
repository without "installing" it first. This approach is perhaps most appropriate for developers,
but it is also useful on older operating systems or on platforms with tight memory and/or storage
constraints.
Because WeeWX is pure-Python and does not need to be compiled, it can be run directly from source without "installing" it first. This approach is perhaps most appropriate for developers, but it is also useful on older operating systems or on platforms with tight memory and/or storage constraints.
The same technique can be used to run from a source directory downloaded as a zip file from
the WeeWX GitHub repository.
This technique can be used to run from a clone of the WeeWX repository, or from a source directory from a zip/tar file.
Although you do not need root privileges to run WeeWX this way, you will need them to set up a
daemon and, perhaps, to change device permissions.
Although you do not need root privileges to run WeeWX this way, you will need them to set up a daemon and, perhaps, to change device permissions.
## Install pre-requisites
Unlike the other install methods, running WeeWX directly from a git clone will require you to
install the pre-requisites manually. Here's how.
Before you run from source, you must install the pre-requisite Python and Python modules.
1. Ensure that Python 3.7 or later is installed. You will also need pip and `venv`.
1. Ensure that Python 3.7 or later is installed.
2. Set up and activate a virtual environment in your home directory
2. Ensure that `pip` and `venv` are installed.
3. Create and activate a virtual environment in your home directory
``` {.shell .copy}
python3 -m venv ~/weewx-venv
source ~/weewx-venv/bin/activate
```
3. Make sure pip is up-to-date
``` {.shell .copy}
python3 -m pip install pip --upgrade
```
4. Install the minimum dependencies
4. Install the minimum WeeWX dependencies
``` {.shell .copy}
python3 -m pip install CT3 -y
@@ -54,8 +44,7 @@ install the pre-requisites manually. Here's how.
## Get the code
Use `git` to clone the repository into a directory called `weewx` in your home
directory.
Use `git` to clone the WeeWX repository into a directory called `weewx` in your home directory.
```shell
git clone https://github.com/weewx/weewx ~/weewx
@@ -72,7 +61,7 @@ git clone https://github.com/weewx/weewx ~/weewx
Now that you have the code, create a configuration file and skins:
```{.shell .copy}
# Make sure your virtual environment is still active:
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Then create the station data
python3 ~/weewx/bin/weectl.py station create
@@ -90,19 +79,20 @@ only after you run `weewxd`, as shown in the following step.
The program `weewxd` does the data collection, archiving, uploading, and report
generation. You can run it directly, or as a daemon.
When you run `weewxd` directly, it will print data to the screen. It will stop when you either
control-c or log out.
When you run WeeWX directly, it will print data to the screen. WeeWX will
stop when you log out, or when you terminate it with `control-c`.
```{.shell .copy}
# Make sure your virtual environment is still active:
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Run weewxd
python3 ~/weewx/bin/weewxd.py
```
To run `weewxd` as a daemon, install a systemd or init file that is appropriate for your operating
system. Be sure to use the full path in the virtual environment to the Python interpreter and
`weewx.py`. Examples are included in the `util` directory.
To run `weewxd` as a daemon, install a systemd or init file that is
appropriate for your operating system. Be sure to use the full path in the
virtual environment to the Python interpreter and `weewx.py`. Examples are
included in the `util` directory.
## Verify
@@ -115,7 +105,8 @@ your station information and data.
!!! Note
Not all browsers understand the tilde ("`~`") mark. You may
have to substitute an explicit path to your home directory.
have to substitute an explicit path to your home directory,
for example, `file:///home/jackhandy` instead of `~`.
If you have problems, check the system log for entries from `weewxd`.

315
docs_src/quickstarts/pip.md
View File

@@ -3,171 +3,160 @@
This is a guide to installing WeeWX using [pip](https://pip.pypa.io). It can
be used to install WeeWX on almost any operating system, including macOS.
WeeWX V5 requires Python 3.7 or greater. Python 2, or earlier versions of Python 3, will not work.
If you are constrained by this, you can install WeeWX V4, which runs with Python 2.7, 3.5,
and 3.6, although it is not supported. You are best off installing Python 3.7+ on your system.
WeeWX V5 requires Python 3.7 or greater. Python 2, or earlier versions of
Python 3, will not work.
Although you do not need root privileges to install and configure WeeWX, you will need them to set
up a daemon and, perhaps, to change device permissions.
Although you do not need root privileges to install and configure WeeWX, you
will need them to set up a daemon and, perhaps, to change device permissions.
While there are many ways to install WeeWX using pip (see the wiki document [pip install
strategies](https://github.com/weewx/weewx/wiki/pip-install-strategies) for a partial list), we
recommend creating a _virtual environment_ using `venv`, because it is the least likely to disturb
the rest of your system. It's worth reading about
[`venv`](https://docs.python.org/3/library/venv.html) in the Python3 documentation.
While there are many ways to install WeeWX using pip (see the wiki document [pip install strategies](https://github.com/weewx/weewx/wiki/pip-install-strategies) for a partial list), we recommend creating a _Python virtual environment_, because it is the least likely to disturb the rest of your system. It is worth reading about [`venv`](https://docs.python.org/3/library/venv.html) in the Python3 documentation.
!!! Note
WeeWX can be installed on any operating system that offers Python 3.7 or later.
However, you may need to install `pip`. See [Installing pip with Linux Package Managers](https://packaging.python.org/en/latest/guides/installing-using-linux-tools/). The [installation directions](https://pip.pypa.io/en/stable/installation/) on the pip website may also be useful.
You will also need `venv`. If `venv` is not available, you may substitute `virtualenv`, which can be installed using pip.
## Install in a virtual environment
To install WeeWX in a virtual environment, follow the directions below for your system. If you
are using MySQL or MariaDB, be sure to see the additional tab labeled `MySQL`.
To install WeeWX in a virtual environment, follow the directions below for
your system. If you plan to use MySQL or MariaDB, be sure to see the
`MySQL/MariaDB` tab.
!!! Install
When finished, the WeeWX executables will have been installed in `~/weewx-venv/bin`, while the WeeWX libraries and dependencies will have been installed in `~/weewx-venv/lib/python3.x/site-packages`, where `3.x` is the version of Python you used.
=== "Debian"
=== "Debian"
_Tested with Debian 10, 12, RPi OS 32-bit, Ubuntu 20.04, and 22.04._
```{ .shell .copy }
sudo apt update
sudo apt install python3-pip -y
sudo apt install python3-venv -y
```{ .shell .copy }
sudo apt update
sudo apt install python3-pip -y
sudo apt install python3-venv -y
# Create the virtual environment:
python3 -m venv ~/weewx-venv
# Create the virtual environment:
python3 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment:
source ~/weewx-venv/bin/activate
# Activate the virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3 -m pip install weewx
```
=== "Rocky 8"
_Tested with Rocky 8.7._
```{ .shell .copy }
sudo yum update
# Check your version of Python. You must have 3.7 or later
python3 -V
# If it is less than Python 3.7, install a later version of Python.
# For example, this would install Python 3.11.
# Afterwards, you must remember to invoke Python using "python3.11", NOT "python3"
sudo yum install python3.11 -y
sudo yum install python3.11-pip -y
# Create the virtual environment:
python3.11 -m venv ~/weewx-venv
# Activate the virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3.11 -m pip install weewx
```
=== "Rocky 9"
_Tested with Rocky 9.1 and 9.2._
```{ .shell .copy }
sudo yum update
sudo yum install python3-pip -y
# Create the virtual environment:
python3 -m venv ~/weewx-venv
# Activate the virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3 -m pip install weewx
```
=== "openSUSE"
_Tested with openSUSE Leap 15.5._
```{ .shell .copy }
sudo zypper refresh
# Check your version of Python. You must have 3.7 or later
python3 -V
# If it is less than Python 3.7, install a later version of Python.
# For example, this would install Python 3.11.
# Afterwards, you must remember to invoke Python using "python3.11", NOT "python3"
sudo zypper install -y python311
# Create the virtual environment:
python3.11 -m venv ~/weewx-venv
# Activate the virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3.11 -m pip install weewx
```
=== "macOS"
_Tested on macOS 13.4 (Ventura)_
```{ .shell .copy }
# Create the virtual environment:
python3 -m venv ~/weewx-venv
# Activate the virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3 -m pip install weewx
```
=== "Other"
Generally, WeeWX can be installed on any operating system that offers a version of
Python 3.7 or later.
You may need to install pip. See [Installing pip with Linux Package
Managers](https://packaging.python.org/en/latest/guides/installing-using-linux-tools/). The
[installation directions](https://pip.pypa.io/en/stable/installation/) on the pip website
may also be useful.
You will also need `venv`. If it is not on your system, and your Linux Package Manager does
not offer a version, then you can substitute `virtualenv`, which can be installed using pip.
# Install WeeWX into the virtual environment:
python3 -m pip install weewx
```
_Tested with Debian 10, 12, RPi OS 32-bit, Ubuntu 20.04, and 22.04._
=== "Redhat 8"
=== "MySQL"
```{ .shell .copy }
sudo yum update
If you plan on using MySQL or MariaDB with `sha256_password` or `caching_sha2_password`
authentication, you will also need to install the module `cryptography`. On some operating
systems this can be a bit of a struggle, but the following usually works. The key step
is to update pip before trying the install.
```{.shell .copy}
# Make sure your virtual environment is still active
source ~/weewx-venv/bin/activate
# Make sure pip is up-to-date
python3 -m pip install pip --upgrade
# Install cryptography
python3 -m pip install cryptography
```
# Check your version of Python. You must have 3.7 or later
python3 -V
# If it is less than Python 3.7, install a later version of Python.
# For example, this would install Python 3.11.
# Afterwards, you must remember to invoke Python using "python3.11", NOT "python3"
sudo yum install python3.11 -y
sudo yum install python3.11-pip -y
# Create the virtual environment:
python3.11 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3.11 -m pip install weewx
```
_Tested with Rocky 8.7._
When finished, the WeeWX executables will have been installed in `~/weewx-venv/bin`, while the
WeeWX libraries and dependencies will have been installed in `~/weewx-venv/lib/python3.x/site-packages`,
where `3.x` is the version of Python you used.
=== "Redhat 9"
```{ .shell .copy }
sudo yum update
sudo yum install python3-pip -y
# Create the virtual environment:
python3 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3 -m pip install weewx
```
_Tested with Rocky 9.1 and 9.2._
=== "openSUSE"
```{ .shell .copy }
sudo zypper refresh
# Check your version of Python. You must have 3.7 or later
python3 -V
# If it is less than Python 3.7, install a later version of Python.
# For example, this would install Python 3.11.
# Afterwards, you must remember to invoke Python using "python3.11", NOT "python3"
sudo zypper install -y python311
# Create the virtual environment:
python3.11 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3.11 -m pip install weewx
```
_Tested with openSUSE Leap 15.5._
=== "macOS"
```{ .shell .copy }
# Create the virtual environment:
python3 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3 -m pip install weewx
```
_Tested on macOS 13.4 (Ventura)_
=== "Other"
```{ .shell .copy }
# Create the virtual environment:
python3 -m venv ~/weewx-venv
# Activate the WeeWX virtual environment:
source ~/weewx-venv/bin/activate
# Install WeeWX into the virtual environment:
python3 -m pip install weewx
```
=== "MySQL/MariaDB"
If you plan on using MySQL or MariaDB with `sha256_password` or `caching_sha2_password`
authentication, you will also need to install the module `cryptography`. On some operating
systems this can be a bit of a struggle, but the following usually works. The key step
is to update pip before trying the install.
```{.shell .copy}
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Make sure pip is up-to-date
python3 -m pip install pip --upgrade
# Install cryptography
python3 -m pip install cryptography
```
## Provision a new station
While the installation instructions above download WeeWX and install it in a virtual environment,
they do not set up the configuration specific to your station, nor do they set up the reporting
skins. That is the job of the tool `weectl`. This step also does not require root privileges.
```{ .shell .copy }
# Make sure your virtual environment is still active
source ~/weewx-venv/bin/activate
# Then create the station data
weectl station create
```
While the instructions above install WeeWX, they do not set up the configuration specific to your station, nor do they set up the reporting skins. That is the job of the tool `weectl`.
The tool `weectl` will ask you a series of questions, then create a directory
`~/weewx-data` in your home directory with a new configuration file. It will
@@ -175,6 +164,13 @@ also install skins, documentation, utilitiy files, and examples in the same
directory. The database and reports will also go into that directory, but
only after you run `weewxd`, as shown in the following step.
```{ .shell .copy }
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Then create the station data
weectl station create
```
## Run `weewxd`
@@ -184,11 +180,11 @@ generation. You can run it directly, or as a daemon.
### Run directly
When you run WeeWX directly, it will print data to the screen, and WeeWX will
stop when you either control-c or log out.
When you run WeeWX directly, it will print data to the screen. WeeWX will
stop when you log out, or when you terminate it with `control-c`.
```{ .shell .copy }
# Make sure your virtual environment is still active
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Then run weewxd:
weewxd
@@ -246,7 +242,12 @@ see your station information and data.
~/weewx-data/public_html/index.html
If there are problems, check the system log.
!!! Note
Not all browsers understand the tilde ("`~`") mark. You may
have to substitute an explicit path to your home directory,
for example, `file:///home/jackhandy` instead of `~`.
If you have problems, check the system log for entries from `weewxd`.
## Configure
@@ -259,7 +260,7 @@ probably want to switch to using real hardware. This is how to reconfigure.
```{ .shell .copy }
# Stop the weewx daemon:
sudo systemctl stop weewx
# Make sure the WeeWX virtual environment is active
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Reconfigure to use your hardware:
weectl station reconfigure
@@ -274,7 +275,7 @@ probably want to switch to using real hardware. This is how to reconfigure.
```{ .shell .copy }
# Stop the weewx daemon:
sudo /etc/init.d/weewx stop
# Make sure the WeeWX virtual environment is active
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Reconfigure to use your hardware:
weectl station reconfigure
@@ -289,7 +290,7 @@ probably want to switch to using real hardware. This is how to reconfigure.
```{ .shell .copy }
# Stop the weewx daemon:
sudo launchctl unload /Library/LaunchDaemons/com.weewx.weewxd.plist
# Make sure the WeeWX virtual environment is active
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Reconfigure to use your hardware:
weectl station reconfigure
@@ -339,7 +340,7 @@ See the [*User Guide*](../../usersguide) and
Get the latest release using `pip`:
```{ .shell .copy }
# Make sure the WeeWX virtual environment is active
# Activate the WeeWX virtual environment
source ~/weewx-venv/bin/activate
# Upgrade the code base
python3 -m pip install weewx --upgrade
@@ -373,8 +374,6 @@ If you installed a daemon configuration, remove it.
=== "systemd"
_Systems that use systemd, e.g., Debian, Redhat, SUSE_
```{ .shell .copy }
sudo systemctl stop weewx
sudo systemctl disable weewx
@@ -383,8 +382,6 @@ If you installed a daemon configuration, remove it.
=== "sysV"
_Systems that use SysV init, e.g., Slackware, Devuan, Puppy, DD-WRT_
```{ .shell .copy }
sudo /etc/rc.d/init.d/weewx stop
sudo update-rc.d weewx remove
@@ -398,7 +395,7 @@ If you installed a daemon configuration, remove it.
sudo rm /Library/LaunchDaemons/com.weewx.weewxd.plist
```
To delete the applications and code, simply remove the WeeWX virtual environment:
To delete the applications and code, remove the WeeWX virtual environment:
```{ .shell .copy }
rm -r ~/weewx-venv