Skip to content

Commit

Permalink
fix: README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Friedjof
Friedjof committed Oct 15, 2024
1 parent 798d4f0 commit ca0b016
Show file tree
Hide file tree
Showing 3 changed files with 93 additions and 94 deletions.
12 changes: 10 additions & 2 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ down:
@echo "Stopping"
@docker compose down

logs:
@echo "Showing logs"
@docker compose logs -f

restart: down up

demo: build up

clean: down
Expand Down Expand Up @@ -50,15 +56,17 @@ release:
@echo "Pushing tag $(v)"
@git push origin $(v)


version:
@echo "Updating version.txt with latest tag"
@TAG=$(shell git describe --tags --abbrev=0) && \
echo "Latest tag: $$TAG" && \
echo $$TAG > version.txt && \
echo "version.txt updated with tag $$TAG"


admin:
@echo "Creating superuser"
@python manage.py createsuperuser

shell:
@echo "Starting shell"
@python manage.py shell
175 changes: 83 additions & 92 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,116 +1,107 @@
# LaundryTracker

LaundryTracker is a simple web application built with Django that allows users to track the availability and status of laundry machines (washers and dryers) in a building. The application features a real-time status update system where users can view whether a machine is available, running, finished, or defective. Additionally, users can set timers for machines and view the remaining time on active machines.
**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

- Track the status of laundry machines (Available, Running, Finished, Defective).
- Real-time updates of machine statuses every 10 seconds via background server polling.
- User-friendly interface for setting timers on machines.
- Ability to mark machines as "Available" after they finish running.
- CSRF protection enabled for secure communication.
- **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

## Screenshots
![demo-home](/static/media/demo-home.png)
![demo-done](/static/media/demo-done.png)
![demo-report-defect](/static/media/demo-report-defect.png)

## Installation

To get started with LaundryTracker, follow the steps below to set up the project on your local machine.

### Requirements

- Python 3.x
- Django 3.x or higher
- Redis (if using Celery for background tasks)

### Setup development environment

1. **Clone the repository:**
```bash
git clone <repository-url>
cd laundrytracker
```

2. **Create and activate a virtual environment:**
```bash
python -m venv venv
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
```

3. **Install dependencies:**
```bash
pip install -r requirements.txt
```

4. **Apply migrations:**
```bash
python manage.py migrate
```

5. **Run the development server:**
```bash
python manage.py runserver
```

6. **Run background tasks:**
```bash
python manage.py simulate_cron --interval 10
```

7. **Access the application:**
Open your browser and go to `http://127.0.0.1:8000`.

## Docker

To set up and run the LaundryTracker application using Docker and Docker Compose, follow these steps:

### Environment Variables

Create a `.env` file in the root directory of your project with the following content:
```env
DJANGO_SECRET_KEY='<random-django-secret-string>' # generate a random string for the secret key
DJANGO_DEBUG='False' # set to 'True' for development
DJANGO_ALLOWED_HOSTS='your-domain.com,localhost' # this 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='<admin-email>' # this is the default superuser email
DJANGO_SUPERUSER_PASSWORD='<admin-password>' # this is the default superuser password
TLS_ACTIVE='True' # set to 'False' if you don't want to use HTTPS
```bash
git clone https://github.com/Friedjof/LaundryTracker.git
```

### Build and Run the Docker Container

1. **Build the Docker container**:
```bash
docker-compose build
```

2. **Run the Docker container in detached mode**:
```bash
docker-compose up -d
```

This will start the LaundryTracker application and make it accessible at `http://localhost:8000`.
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='<random-django-secret-string>' # 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='<admin-email>' # this is the default superuser email
DJANGO_SUPERUSER_PASSWORD='<admin-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

> Acces the admin panel at `http://<your-domain>/admin/` and log in with the superuser credentials you created.
> Access the admin panel at `http(s)://<your-domain>/admin/` and log in with the superuser credentials you created.
> You can add buildings, machines, and notes in the admin panel.
Once the server is running, you can navigate to the home page, select your building, and view the status of each machine.
![admin-panel](/static/media/demo-administration-panel.png)

- If a machine is **running**, you will see the remaining time displayed.
- If a machine is **finished**, you can mark it as **Available** and set a new timer.
- The application updates the machine status every 10 seconds to reflect real-time changes.
### 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
> Coming soon…

## Configuration

- The building codes and machine configurations can be updated in the database.
- You can configure the update interval and other settings in the JavaScript files and Django views.
- **`/<uuid:building>/`**: Displays an overview of the selected building.
- **`/<uuid:building>/laundry/<uuid:machine_id>/`**: Allows users to set a timer for the specified machine.
- **`/<uuid:building>/laundry/<uuid:machine_id>/available/`**: Returns the availability status of the machine.
- **`/<uuid:building>/laundry/<uuid:machine_id>/notes/`**: Retrieves notes associated with the specified machine.
- **`/<uuid:building>/laundry/<uuid:machine_id>/defect/`**: Marks the machine as defective.
- **`/<uuid:building>/laundry/<uuid:machine_id>/repair/`**: Marks the machine as repaired after maintenance.
- **`/<uuid:building>/laundry/<uuid:machine_id>/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

Expand Down
Binary file added static/media/demo-administration-panel.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit ca0b016

Please sign in to comment.