Skip to main content

🌍 Web Page | 💻 Source Code | 🚀 Releases

🎁 Packages | 🐳 Docker Hub

🔑 logkey

A lightweight Python application to log user inputs into a CSV file with Docker support for easy deployment and GitHub Actions to automate key workflows.

logkey project banner

📌 About​

logkey is a Python-based application that logs user input into a CSV file. Users can configure the exit key and the CSV file name via command-line arguments. By default, the exit key is q, and the inputs are stored in inputs.csv.

🧠 Philosophy​

The philosophy behind logkey is to demonstrate the use of Python with Docker and how GitHub Actions can be used to automate key workflows like GitHub Pages deployment, release management, and Docker image packaging.

🔑 Key Features​

  • Docker Support: Run the application in a Docker container for easy deployment and portability.
  • GitHub Actions: Automate workflows for documentation deployment, release management, and Docker image packaging.
  • Open Source: Licensed under the MIT License, allowing anyone to use, modify, and distribute it freely.

🚀 How to Run?​

🐍 Without Docker​

📂 Clone the Repository​

Terminal
git clone https://github.com/imfsiddiqui/logkey
cd logkey
info
  • imfsiddiqui is the GitHub username.
  • logkey is the repository name.

📦 Install Dependencies​

Ensure Python installed, then run:

Terminal
pip install -r requirements.txt

▶️ Run the Application​

Terminal
python src/logkey/logkey.py --exit-key <key> --csv-file <filename>
  • Replace <key> with your desired exit key (default is q).
  • Replace <filename> with your desired CSV file name (default is inputs.csv).

💡 Example​

Terminal
python src/logkey/logkey.py --exit-key x --csv-file user_inputs.csv

This will log inputs to user_inputs.csv and exit when x is pressed.

🐳 With Docker​

Ensure Docker installed, then follow the below instructions.

info

In all the following commands:

  • imfsiddiqui is the Docker Hub username.
  • logkey is the Docker image name.

📥 Pull the Docker Image​

Pull the prebuilt Docker image from Docker Hub:

Terminal
docker pull imfsiddiqui/logkey

▶️ Run the Application​

Use the following command to run the application in a Docker container:

🐧 Linux​
Terminal
docker run -it --rm -v $(pwd)/:/app/data/ imfsiddiqui/logkey \
  python src/logkey/logkey.py --exit-key <key> --csv-file /app/data/<filename>
🪟 Windows: PowerShell​
Terminal
docker run -it --rm -v ${PWD}/:/app/data/ imfsiddiqui/logkey `
  python src/logkey/logkey.py --exit-key <key> --csv-file /app/data/<filename>
  • The -v $(pwd)/:/app/data/ or -v ${PWD}/:/app/data/ option mounts the current working directory from host machine to the /app/data/ directory inside the container. This ensures that any CSV files created or updated by the application are stored persistently on host machine, even after the container stops.
  • Replace <key> with your desired exit key (default is q).
  • Replace <filename> with your desired CSV file name (default is inputs.csv).

💡 Example​

🐧 Linux​
Terminal
docker run -it --rm -v $(pwd)/:/app/data/ imfsiddiqui/logkey \
  python src/logkey/logkey.py --exit-key x --csv-file /app/data/user_inputs.csv
🪟 Windows: PowerShell​
Terminal
docker run -it --rm -v ${PWD}/:/app/data/ imfsiddiqui/logkey `
  python src/logkey/logkey.py --exit-key x --csv-file /app/data/user_inputs.csv

This will log inputs to user_inputs.csv in the current directory on host machine and exit when x is pressed.

🛠️ Development​

If made any changes to the Python script src/logkey/logkey.py or update the requirements.txt file, follow these steps to rebuild and publish the Docker image.

📋 Update the requirements.txt File​

New dependencies or libraries can be added to the project by adding their name in the requirements.txt file.

🏗️ Build the Docker Image​

Rebuild the Docker image to include the latest changes:

🐧 Linux​

Terminal
docker build -t logkey:latest -f ./Dockerfile .

🪟 Windows: PowerShell​

Terminal
docker build -t logkey:latest -f .\Dockerfile .

🧪 Test the Docker Image Locally​

Run the updated Docker image locally to ensure everything works as expected:

🐧 Linux​

Terminal
docker run -it --rm -v $(pwd)/:/app/data/ logkey:latest \
  python src/logkey/logkey.py --exit-key x --csv-file /app/data/user_inputs.csv

🪟 Windows: PowerShell​

Terminal
docker run -it --rm -v ${PWD}/:/app/data/ logkey:latest `
  python src/logkey/logkey.py --exit-key x --csv-file /app/data/user_inputs.csv

🏷️ Tag the Docker Image​

Tag the Docker image with a version number or latest:

Terminal
docker tag logkey:latest imfsiddiqui/logkey:<version>

Replace <version> with the appropriate version number e.g. 1.0.1 or latest.

📤 Push the Docker Image to Docker Hub​

Publish the updated Docker image to Docker Hub:

Terminal
docker push imfsiddiqui/logkey:<version>

latest tag can also be published:

Terminal
docker push imfsiddiqui/logkey:latest

✅ Verify the Published Image​

Pull the image from Docker Hub to verify it was published correctly:

Terminal
docker pull imfsiddiqui/logkey:<version>

or

Terminal
docker pull imfsiddiqui/logkey:latest

Run the pulled image to ensure it works as expected:

🐧 Linux​

Terminal
docker run -it --rm -v $(pwd)/:/app/data/ imfsiddiqui/logkey \
  python src/logkey/logkey.py --exit-key x --csv-file /app/data/user_inputs.csv

🪟 Windows: PowerShell​

Terminal
docker run -it --rm -v ${PWD}/:/app/data/ imfsiddiqui/logkey `
  python src/logkey/logkey.py --exit-key x --csv-file /app/data/user_inputs.csv

By these steps, this can be ensured that updates are reflected in the Docker image and published for others to use.

🐙 GitHub Actions​

Following GitHub Actions are being used to automate key workflows:

🤖 .github/workflows/pages.yaml​

Automatically builds and deploys the documentation website using Jekyll whenever changes are pushed to the default branch main, a new tag starting with v (e.g., v1.0.0) is pushed, or the workflow is manually triggered.

🤖 .github/workflows/release.yaml​

Creates a new GitHub release when a tag starting with v is pushed. This automates the release process and makes new versions easily accessible to users.

🤖 .github/workflows/package.yaml​

Builds a Docker image and publishes it to GitHub Container Registry (ghcr.io) every time a new tag starting with v (e.g., v1.0.0) is pushed. This ensures the latest version of the application is always available as a container image.

📄 Important Documents​

📜 License​

This project is licensed under the MIT License, allowing anyone to use, modify, and distribute it freely for personal or commercial purposes.

Last updated on