Before you begin, ensure you have the following software installed on your local machine:

• Git: A version control system. Download Git
• Python: Version 3.10 or newer. Download Python
• MySQL/MariaDB: A local database server (e.g., XAMPP, WAMP, MAMP, or a direct installation).

1. Clone the Repository

git clone https://github.com/KurdishWikipedia/bijar.git

2. Create Virtual Environment & Install Dependencies

Open a terminal and create a virtual environment inside the www/python/ directory.

python -m venv www/python/venv

Next, activate the environment.

• Windows (Command Prompt): .\www\python\venv\Scripts\activate.bat
• Windows (PowerShell): .\www\python\venv\Scripts\Activate.ps1
• macOS & Linux (bash/zsh): source www/python/venv/bin/activate

Now, install the required packages:

pip install -r requirements.txt

Finally, deactivate the environment:

deactivate

3. Set Up the Database

• Start your local MySQL/MariaDB server.
• Create a new database (e.g., local_database). You can do this through your database program's GUI or with a command-line client:

  CREATE DATABASE local_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

• Database File: The database dump (.sql file) is required. To obtain it, please contact the project maintainer on their Wikipedia user talk page. Once you have the file, import it into the database you just created.

4. Configure Environment Variables

The application requires a local .env file for settings and secrets.

Navigate to the application's source directory:

cd www/python/src

Create the file by copying the sample for your operating system:

# On Windows
copy .env.sample .env

# On macOS & Linux
cp .env.sample .env

Open the new .env file in a text editor and follow the instructions inside to add your local configuration.

5. Generate Word Statistics

Note: This script pre-caches word statistics in a JSON file for the home page, preventing a startup timeout on Toolforge and ensuring the application runs efficiently in both local and production environments.

Activate the virtual environment:

• Windows (Command Prompt): .\www\python\venv\Scripts\activate.bat
• Windows (PowerShell): .\www\python\venv\Scripts\Activate.ps1
• macOS & Linux (bash/zsh): source www/python/venv/bin/activate

With your local database server running, execute the script:

python run.py generate_stats.py

After it completes, deactivate the environment:

deactivate

6. Get the Gadget Source Code

Gadget JS/CSS source code

To test changes locally, you can use a browser extension like Tampermonkey to inject your local JS/CSS files into live Wikipedia pages.

Important Browser Security Note: When developing locally, the gadget runs on https://ckb.wikipedia.org while your Flask server runs on http://127.0.0.1. Modern browsers block this cross-origin request by default (CORS policy). You may need to temporarily disable web security features in your browser to allow flask-cors to work. This is for local development only and should be handled with care.

7. Run the Application

1. Start your database: Ensure your local database server is running.

2. Run the development server: From the project's root directory (bijar/), execute the appropriate script for your operating system. This will automatically manage the virtual environment and start the Flask server.

   • On Windows (cmd/PowerShell):

     .\run.bat

   • On macOS, Linux, or Git Bash:

     ./run.sh

The application will now be running at http://127.0.0.1:5000 and http://localhost:5000.

(Replace <username>, <tool_name>, and <database_name> with your credentials.)

1. Connect to Toolforge

ssh <username>@login.toolforge.org
become <tool_name>

2. Clone the Repository

git clone https://github.com/KurdishWikipedia/bijar.git .

3. Create Virtual Environment & Install Dependencies

See the official documentation on Python Virtual Environments and Packages on Toolforge for more details.

toolforge webservice python3.13 shell
mkdir -p $HOME/www/python
python3 -m venv $HOME/www/python/venv
source $HOME/www/python/venv/bin/activate
pip install --upgrade pip wheel
pip install -r $HOME/requirements.txt
exit

4. Set Up the Database on Toolforge

See the Toolforge ToolsDB documentation for more information.

# Connect to MariaDB
sql tools
# Create the database
CREATE DATABASE <database_name>;
# Verify creation
SHOW DATABASES;
# Exit the MariaDB prompt
exit

Upload your local_database.sql file from your computer to your tool's home directory. In a new local terminal:

scp local_database.sql <username>@tools-login.wmflabs.org:/data/project/<tool_name>/

From your Toolforge shell, verify the upload and import the data:

# Verify the file exists
ls -l *.sql
# Import the SQL file into your tool's database
mysql --defaults-file=$HOME/replica.my.cnf -h tools.db.svc.wikimedia.cloud <database_name> < /data/project/<tool_name>/local_database.sql
# No output indicates success.

Check that the tables were imported successfully:

sql tools
USE <database_name>;
SHOW TABLES;
# You should see all tables now.
exit

(Optional but recommended) Remove the SQL file after import. Toolforge advises against storing backups permanently on the platform.

cd ~
rm local_database.sql

5. Configure Environment Variables

Create and edit the .env file using the provided sample. The file contains all necessary instructions.

cd www/python/src
cp .env.sample .env
# Edit .env using the instructions inside the file.

Finally, secure the file:

chmod 600 .env

6. Generate Word Statistics

Note: To prevent a startup timeout on Toolforge, this script pre-caches word statistics in a JSON file for the home page.

Activate the virtual environment:

source www/python/venv/bin/activate

Run the script manually to generate the statistics. This process can be slow on Toolforge, depending on the size of the database.

python run.py generate_stats.py

After the script finishes, deactivate the environment:

deactivate

TIP: Since this script's execution is slow on Toolforge, it is more efficient to automate it with a scheduled cron job rather than running it manually.

7. Start the Webservice

toolforge webservice python3.13 start

See the official documentation about backups for details.

Note: Toolforge does not recommend storing backups on the platform permanently.

1. Export: Run this command to create a private SQL dump. The file will be saved in your tool's home ($HOME) directory.

# use umask to make the dump private (use unless the database is public)
toolforge jobs run --command 'umask o-r; ( mariadb-dump --defaults-file=$TOOL_DATA_DIR/replica.my.cnf --host=tools-readonly.db.svc.wikimedia.cloud <database_name> > $TOOL_DATA_DIR/<database_name>-$(date -I).sql )' --image mariadb backup --wait

Verify the file was created using ls -l *.sql from the $HOME directory.

2. Download: From your local PC's terminal, use scp to download the file.

scp <username>@login.toolforge.org:/data/project/<tool_name>/<database_name>-YYYY-MM-DD.sql .