https://github.com/friedjof/laundrytracker

LaundryTracker is a web application for monitoring the status of washers and dryers with real-time updates and a user-friendly interface. It allows users to view machine status, set timers, and mark machines as available
https://github.com/friedjof/laundrytracker

django docker docker-compose dryer laundry laundry-management sqlite tracking washing washing-machine

Last synced: 16 days ago
JSON representation

LaundryTracker is a web application for monitoring the status of washers and dryers with real-time updates and a user-friendly interface. It allows users to view machine status, set timers, and mark machines as available

• Host: GitHub
• URL: https://github.com/friedjof/laundrytracker
• Owner: Friedjof
• License: gpl-3.0
• Created: 2024-10-09T15:01:11.000Z (about 1 month ago)
• Default Branch: main
• Last Pushed: 2024-10-27T19:00:45.000Z (21 days ago)
• Last Synced: 2024-10-27T23:08:39.239Z (21 days ago)
• Topics: django, docker, docker-compose, dryer, laundry, laundry-management, sqlite, tracking, washing, washing-machine
• Language: Python
• Homepage:
• Size: 22.6 MB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# LaundryTracker

**LaundryTracker** is a solution for monitoring washing machines and dryers in communal laundry rooms, commonly found in shared living spaces or dormitories.

Users themselves collect the data by setting timers for the machines or reporting defects.

This allows other users to see in real-time which machines are available or out of order.

Additionally, it helps the property management quickly identify defective machines and arrange for repairs efficiently.

> **Note:** The quality of the displayed data depends on user input. Reliable usage can only be ensured through accurate and up-to-date information.

> This project is still in development and may include bugs or incomplete features. Feel free to contribute to the project by submitting a pull request.

## Features

- **Timers** can be set by users when they start using a machine.

- **Defective machines** can be marked as defective or temporarily defective, with a short note.

- **Admin panel** allows configuration of the app.

- **Special links** are required for users to control machines, helping to prevent unauthorized use.

- **Analytics dashboard** provides administrators with detailed usage insights. All changes are logged and visualized in charts.

- **Telegram bot** can be set up via the admin panel. It sends various events to configured Telegram channels and notifies users via push notifications (optional).

- **Moderators** can be assigned via the admin panel to manage individual laundry rooms (in development).

## Demo Screenshots

  

    

    

    

  

  

    

    

    

  

## Installation

```bash

git clone https://github.com/Friedjof/LaundryTracker.git

```

The project can be started in two ways:

- **For development**, the project can be started as usual with Django.

- Alternatively, you can build the project as a **Docker container** or use the existing Docker image from this repository.

### Development

1. Create a virtual Python environment and activate it: `python -m venv venv && source venv/bin/activate`

2. Install the dependencies: `pip install -r requirements.txt`

3. Migrate the database: `python manage.py migrate`

4. Start Django: `python manage.py runserver`

5. To update the database entries in the background, run the following command: `python manage.py simulate_cron --interval 60`

### Production

1. Build the Docker image: `docker compose build --no-cache`

2. Create a `.env` file with the following content:

   ```env

   DJANGO_SECRET_KEY='' # generate a random string for the secret key

   DJANGO_DEBUG='False'                              # set to 'True' for development

   DJANGO_ALLOWED_HOSTS='your-domain.com,localhost'  # the first should be your main domain, multiple domains should be separated by commas

   DJANGO_SUPERUSER_USERNAME='admin'                 # this is the default superuser username

   DJANGO_SUPERUSER_EMAIL=''            # this is the default superuser email

   DJANGO_SUPERUSER_PASSWORD=''      # this is the default superuser password

   TLS_ACTIVE='True'                                 # set to 'False' if you don't want to use HTTPS

   ```

3. Start the Docker container: `docker compose up -d`

Now you can access the LaundryTracker application on port `8000` with your configured domain.

## The Makefile

The project includes a `Makefile` with various commands to simplify development and deployment. You can run the following commands:

- Django commands:

  - `make migrations`: Create the database migrations.

  - `make migrate`: Apply the database migrations.

  - `make admin`: Create a superuser for the Django admin panel.

  - `make shell`: Start the Django shell.

- Docker commands:

  - `make build`: Build the Docker image.

  - `make up`: Start the Docker container.

  - `make down`: Stop the Docker container.

  - `make logs`: Show the Docker container logs.

  - `make restart`: Restart the Docker container.

  - `make clean`: Remove the Docker container and image.

- Python commands:

  - `make requirements`: Freeze the current dependencies to the `requirements.txt` file.

- Deployment commands:

  - `make release`: Saves the version tag in the `version.txt` file, commits it, and pushes it to the repository.

  - After pushing tags to the repository (e.g. like `v1.0.0`), the GitHub Actions workflow will automatically build and push the Docker image to the GitHub Container Registry.

## Usage

> Access the admin panel at `http(s):///admin/` and log in with the superuser credentials you created.

> You can add buildings, machines, and notes in the admin panel.

![admin-panel](/media/demo-admin-panel.png)

### Machine Status

- **Available**: The machine is available for use.

- **Running**: The machine is currently in use.

- **Finished**: The machine has finished its cycle.

- **Defective**: The machine is defective and cannot be used.

- **Blinking**: The machine is blinking, indicating a temporary defect (will automatically switch back to 'Available' after 8 hours).

- **Unknown**: The machine status is unknown (currently not in use).

## API Endpoints

- **`//`**: Displays an overview of the selected building.

- **`//laundry//`**: Allows users to set a timer for the specified machine.

- **`//laundry//available/`**: Returns the availability status of the machine.

- **`//laundry//notes/`**: Retrieves notes associated with the specified machine.

- **`//laundry//defect/`**: Marks the machine as defective.

- **`//laundry//repair/`**: Marks the machine as repaired after maintenance.

- **`//laundry//blinking/`**: Controls the blinking indicator for the machine to signal specific states.

- **`/404`**: Handles invalid requests by returning a 404 error page.

- **`/`**: The homepage of the application.

## Contributing

Contributions to LaundryTracker are welcome! Feel free to fork the repository, make your changes, and submit a pull request.

## License

This project is licensed under the GNU (General Public License) v3.0. See the [`LICENSE`](LICENSE) file for more information.

---

If you have any questions or feedback, feel free to contact us at [[email protected]](mailto:[email protected]).