This document serves to familiarize the Contributor with YOURLS Action by showing how to build and run it from source in a local build environment (Environment). This software populates the YOURLS database from a directory tree of CSV mapping files. This is used to load the Namespaces directory to a Yourls compliant, MySQL database.
In order to build YOURLS Action you must have the following installed in your Environment.
Python and Pip can be downloaded and installed from the official Python website. Ensure you select the appropriate version for your operating system.
As of the last update, the YOURLS Action requires Python 3.6 or later. Check the system’s documentation or codebase for the specific version requirements.
This documentation may refer to the PYTHONPATH environment variable, which indicates the directories where Python looks for modules. If not set, Python will use a default path.
Please refer to the Python official documentation for comprehensive information on Python installation, configuration, and development practices.
python3 --version
pip3 --version
Git can be downloaded and installed from the official Git website. Follow the installation instructions for your specific operating system.
To check the installed Git version, use the following command:
git --version
Docker is used here to launch YOURLS developer runtime service dependencies YOURLS and its database (MySQL).
Docker can be downloaded and installed from the official Docker website. Follow the installation instructions for your specific operating system.
Once Docker is installed, you can verify that it’s running correctly by executing the following command:
docker --version
docker info
Note: To run docker on alpine, you must have sudo privileges.
Choose a starting location to work on your computer:
export SRC_BASE_DIR=/path/to/dev/directory
Clone Yourls Action from your forked github repository to your Environment in a predefined directory location.
cd $SRC_BASE_DIR
git clone git@github.com:<GH_USER>/yourls-action.git
To build the YOURLS database environment, build the MySQL docker image.
cd $SRC_BASE_DIR/yourls-action/yourls-mysql
docker build -t yourls-mysql .
Start the MySQL database:
docker run -d \
-p 3306:3306 \
--name mysql \
-e "MYSQL_ROOT_PASSWORD=amazingpassword" \
yourls-mysql
Create a namespace directory tree, and a CSV mapping file links.csv.
mkdir -p $SRC_BASE_DIR/namespaces/iow
vi $SRC_BASE_DIR/namespaces/iow/links.csv
Next install the python package YOURLS Action, which loads the directory tree into the MySQL database.
cd $SRC_BASE_DIR/yourls-action/yourls-action
# if user has sudo privileges
python3 setup.py install
# else
pip3 install .
Note: Ensure the location you install yourls-action is on your $PATH, otherwise you
won’t be able to use the yourls-action command line interface (CLI).
YOURLS Action uses environment variables to connect to the MySQL database:
export DB_SOCKET_DIR=/var
export YOURLS_DB_HOST=localhost
export YOURLS_DB_PASSWORD=amazingpassword
To run YOURLS Action, use the CLI:
yourls-action run $SRC_BASE_DIR/namespaces
To verify YOURLS action has inserted the URL mappings run the following…
docker exec -it mysql \
sh -c 'mysql -p -h localhost -e \
"USE yourls; SELECT * FROM yourls_url;"'
Note: You will need to provide the MySQL password set above.
The table should appear as follows, with a timestamp of when the row was last updated:
| keyword | url | title | timestamp | ip | clicks |
|---|---|---|---|---|---|
| /usgs/monitoring-location/([a-zA-Z0-9_]+).*$ | https://waterdata.usgs.gov/monitoring-location/$1 | USGS Monitoring Locations | 2024-03-12 18:09:54 | 0.0.0.0 | 0 |
| iow/homepage | https://internetofwater.org | Internet Of Water homepage | 2024-03-12 18:09:54 | 0.0.0.0 | 0 |