HortusFox
A self-hosted collaborative plant management system
(C) 2023 - 2026 by Daniel Brendel
www.hortusfox.com
## Table of Contents
- [Description](#description)
- [Features](#features)
- [Resources](#resources)
- [Installation](#installation)
- [Docker](#docker)
- [Installer](#installer)
- [Manual](#manual)
- [AquaShell](#aquashell)
- [Cronjobs](#cronjobs)
- [Application testing](#application-testing)
- [System requirements](#system-requirements)
- [External services](#external-services)
- [App icons](#app-icons)
- [Weather forecast](#weather-forecast)
- [Plant identification](#plant-identification)
- [Plant information](#plant-information)
- [Console commands](#console-commands)
- [Maintenance scripts](#maintenance-scripts)
- [Tech stack](#tech-stack)
- [Contributing](#contributing)
- [Security](#security)
## Description
HortusFox is a free opensource self-hosted collaborative plant management system which you can use to manage all your plants. It provides an extensive amount of features to assist you in keeping track, taking care, and journal all things about your plants. The system is designed using a per-location approach, which means that plants are always assigned to locations. Not only does the app allow you to manage attributes, photos, notes, logs and many other things around your plants, it does also provide task management, inventory management, an extensive search feature, a calendar, a collaborative group chat and many, many more features. Your personal workspace can be customized via the integrated theme system, allowing for an individual look and feel while managing your plants. Furthermore, developers can leverage the integrated API to create their own third-party custom software for various scenarios. Please see a list of features below.
## Features
- Plant management
- Custom locations
- Tasks system
- Inventory system
- Calendar system
- Search feature
- ️ History feature
- ️ Weather feature
- Group chat
- ⚙️ Profile management
- Themes
- Admin dashboard
- Reminders
- Backups
- REST API
- QR Codes
- Plant identification
## Resources
- [Official Homepage](https://www.hortusfox.com/)
- [Documentation](https://www.hortusfox.com/documentation)
## Installation
### Docker
You can use Docker and Docker Compose to simplify the setup process and ensure consistency across different environments.
Prerequisites
- Docker installed on your system
- Docker Compose installed on your system
Follow these steps:
1. Clone the repository:
```shell
git clone https://github.com/danielbrendel/hortusfox-web.git
cd hortusfox-web
```
2. Set environment variables in the `docker-compose.yml`.
Set your admin user e-mail and password in order to login
```yaml
# Admin login credentials
# services.app.environment
APP_ADMIN_EMAIL: "
[email protected]"
APP_ADMIN_PASSWORD: "password"
```
Set your preferred timezone. Default is UTC.
```yaml
# Timezone setting
# services.app.environment
APP_TIMEZONE: "UTC"
```
If you want composer dependencies to be updated when the app container starts, set the following setting
```yaml
# Update composer dependencies during start if set to true
# services.app.environment
APP_UPDATEDEPS: "true"
```
Set database settings if required. It is recommended to set custom passwords due to security reasons. All other settings can be left unaltered.
```yaml
# Settings used to establish connections to the database
# services.app.environment
DB_HOST: db
DB_PORT: 3306
DB_DATABASE: hortusfox
DB_USERNAME: user
DB_PASSWORD: password
DB_CHARSET: "utf8mb4"
# Settings of the database container
# services.db.environment
MARIADB_ROOT_PASSWORD: my-secret-pw
MARIADB_DATABASE: hortusfox
MARIADB_USER: user
MARIADB_PASSWORD: password
```
You can optionally specify proxy authentication settings for your app
```yaml
# services.app.environment
PROXY_ENABLE: "true"
PROXY_HEADER_EMAIL: "Your e-mail header identifier here"
PROXY_HEADER_USERNAME: "Your username header identifier here"
PROXY_AUTO_SIGNUP: "true"
PROXY_WHITELIST: ""
PROXY_HIDE_LOGOUT: "true"
PROXY_OVERWRITE_VALUES: "true"
```
Note: Setting `PROXY_OVERWRITE_VALUES` to `true` is mandatory if you want to update your proxy authentication settings upon container launch.
3. Pull the image and run the application:
```shell
docker compose pull
docker compose up -d
```
Note: This particular step is also the correct way to upgrade to a new version.
4. The application should now be running on http://localhost:8080.
5. You can now go to the
admin dashboard in order to adjust your workspace settings and also go to your
profile page in order to adjust your user preferences.
### Installer
You can also use the integrated installer in order to install the product. In order for that to do, be sure that you are not running the
system via the internal asatru development server. Instead you might want to, for instance, run the system from the context of a webserver
environment like XAMPP. If you do that, just create a file named do_install (no file extension) in the root directory of the project and
browse to the installer and the system will guide you through the installation process.
```
http://localhost/install
```
Be sure that PHP is installed and both your webserver and mariadb server are running. If there is no vendor folder already created then
the system will try to run Composer in order to install all required dependencies. For that to work you need to have Composer installed
on your system. Although the system tries to create the database for you, sometimes this might fail, so you will have to create the
database before running the installation. However all table migrations will then be created by the system. The system can then be managed
via the admin section (e.g. environment settings, users, locations).
### Manual
In order to manually install HortusFox you need to first setup a PHP environment along with a MariaDB database
and also Composer. Afterwards you can clone or download the repository. Then go to the root directory
of the project and let Composer install the required dependencies.
```shell
composer install
```
Now we need to configure the project. Create a .env file from the .env.example, open it and manage the following variables:
```
…
```
After saving the file you can now let the product create all necessary tables via the following command:
```shell
php asatru migrate:fresh
```
Now you need to insert your initial app settings profile into the database. There are many more settings available, but you can adjust them later in the admin dashboard.
```sql
INSERT INTO `AppModel` (id, workspace, language, created_at) VALUES (
NULL,
'My workspace name',
'en',
CURRENT_TIMESTAMP
);
```
Next you should let the system perform some initial operations
```shell
# Add default plant attributes
php asatru plants:attributes
# Add default calendar classes
php asatru calendar:classes
```
You might now want to start your web server to host the application. If you want to quickly use the inbuilt webserver
you can start it via:
```shell
php asatru serve
```
Now browse to http://localhost:8000/ and you should be redirected to the authentication page.
At this point you need to create your first user. Go to your database control panel and switch to the users table.
Add the user account that should get access to the application with admin privileges. The following is an example:
```sql
INSERT INTO `UserModel` (`name`, `email`, `password`, `admin`) VALUES
(
'Username',
'
[email protected]',
'your_password_token_here',
1
);
```
As you might have noticed the values that you need to customize are name, email, password and admin. All others are left with their default values.
The password hash must be created manually. For testing purposes you might just want to quickly use something like:
```shell
php -r "echo password_hash('test', PASSWORD_BCRYPT);"
```
You may now login with your initial admin user account using your e-mail address and the password of which you have stored the hash in the table.
After logging in, you should then be redirected to the dashboard. Further users can now be created via the admin area. Users can change their
passwords in their profile preferences. They can also reset their password. Therefore an e-mail will be sent to them with restoration instructions.
Each new created user can get a confirmation e-mail with an automatically generated password in order to log in. It is recommended that users change
their passwords after their first login.
Last but not least you need to add all your locations of your local environment to the database. You can do that either via the admin section or
manually by inserting entries into the locations table.
```sql
INSERT INTO `LocationsModel` (`id`, `name`, `icon`, `active`, `created_at`) VALUES
(
NULL,
'Name of location',
NULL,
1,
CURRENT_TIMESTAMP
);
```
The mandatory field is the name of the location (e.g. garden, living room, kitchen, etc).
### AquaShell
If you have [AquaShell](https://github.com/danielbrendel/dnyAquaShell) installed, you can also use the installer script to install the project
on your machine. Therefore the following requirements must be met:
- Web server with PHP and MariaDB installed
- Composer package manager installed
- PHP, MariaDB and Composer must be available via the commandline
- Create a `do_install` file in the project root directory, so that the installer is enabled
If all these requirements are met, you can launch the installer script either interactively or via script arguments.
#### Interactive usage
Run the installer script
```sh
aquashell scripts/install.dnys --launch
```
The installer will prompt you with all required input fields. The `--launch` argument will lead the script to launch `http://localhost` in your default browser when finished.
#### Usage with script arguments
If you want to run the installer script without any prompts, you can just pass every required input field as script arguments
```sh
aquashell scripts/install.dnys --workspace "Your workspace name" --username "Your admin profile name" --email "
[email protected]" --password "your-login-password" --database "hortusfox" --dbhost "localhost" --dbport "3306" --dbuser "root" --dbpw "your-access-password" --continue --launch
```
Since there is a confirmation prompt once all input fields are provided, you can use the `--continue` argument to skip this confirmation.
**Note**: If you don't have a database access password (e.g. due to a local XAMPP installation), you can pass `--dbpw "!"` to specify an empty password.
## Cronjobs
Cronjobs are used to regularly execute specific tasks. For each cronjob you need to set the cronjob token via `cronpw`. Depending on the request method, you can set `cronpw` as POST data or as query parameter. The following cronjobs are available:
```sh
# Used to inform users about overdue tasks. Should be called multiple times per day.
ANY /cronjob/tasks/overdue
# Used to inform users about tasks that are due tomorrow. Should be called multiple times per day.
ANY /cronjob/tasks/tomorrow
# Used to check for recurring tasks and reset them accordingly. Should be called at least