A self-hosted collaborative plant management system
(C) 2023 - 2024 by Daniel Brendel
HortusFox is a self-hosted collaborative plant management system which you can use in your own environment to manage all your plants. You can add your plants with various details and photos and assign them to a location of your environment. There is a dashboard available that shows all important overview information. The system does also feature a warning system in order to indicate which plants need special care, user authentication, tasks, inventory management, collaborative chat and a history log of what actions users have taken. The system features collaborative management, so you can manage your plants with multiple users.
- 🪴 Plant management
- 🏠 Custom locations
- 📜 Tasks system
- 📖 Inventory system
- 🔍 Search feature
- 🕰️ History feature
- 💬 Group chat
- ⚙️ Profile management
- 🔑 Admin dashboard
- 📢 Reminders
Using Docker and Docker Compose simplifies the setup process and ensures consistency across different environments.
Prerequisites
- Docker installed on your system
- Docker Compose installed on your system
Follow these steps:
- Clone the repository:
git clone [email protected]:danielbrendel/hortusfox-web.git
cd hortusfox-web- Set environment variables
Configure the application using environment variables.
Set these in your docker-compose.yml file:
| Variable | Description | Example | Required |
|---|---|---|---|
| APP_ADMIN_EMAIL | Administrator email for logging in | "[email protected]" | No |
| APP_ADMIN_PASSWORD | Administrator password, will be autogenerated if blank | "password" | No |
| APP_BASE_DIR | "" | Yes | |
| APP_DEBUG | Enable debug mode | false | Yes |
| APP_LANG | Base language of the app interface | "en" | Yes |
| APP_WORKSPACE | Your workspace name | "My plant home" | Yes |
| APP_ENABLE_SCROLLER | Shows a back-to-top scroller on the bottom right | "true" | Yes |
| APP_OVERLAY_ALPHA | In case you are using a custom bg image | "null" | Yes |
| APP_ENABLE_CHAT | Enable chat in application | "true" | Yes |
| APP_ONLINE_MINUTE_LIMIT | Delay before showing offline | 5 | Yes |
| APP_SHOW_CHAT_ONLINE_USERS | Show online users in chat | "false" | Yes |
| APP_SHOW_CHAT_TYPING_INDICATOR | Show chat typing indicator | "false" | Yes |
| APP_OVERDUE_TASK_HOURS | Hours before considering a task overdue | 10 | Yes |
| APP_CRON_PW | Password for cron tasks | "someStrongPassword" | Yes |
| APP_CRON_MAIL_LIMIT | 5 | Yes | |
| APP_ENABLE_HISTORY | Enable the history section of the application | "true" | Yes |
| APP_HISTORY_NAME | Name for the history section | "History" | Yes |
| APP_ENABLE_PHOTO_SHARE | Whether photo sharing shall be activated | "false" | Yes |
| PHOTO_RESIZE_FACTOR_DEFAULT | 1.0 | Yes | |
| PHOTO_RESIZE_FACTOR_1 | 0.5 | Yes | |
| PHOTO_RESIZE_FACTOR_2 | 0.4 | Yes | |
| PHOTO_RESIZE_FACTOR_3 | 0.4 | Yes | |
| PHOTO_RESIZE_FACTOR_4 | 0.3 | Yes | |
| PHOTO_RESIZE_FACTOR_5 | 0.2 | Yes | |
| DB_HOST | Database host | db | Yes |
| DB_PORT | Database port | 3306 | Yes |
| DB_DATABASE | Database name | hortusfox | Yes |
| DB_USERNAME | Database user | root | Yes |
| DB_PASSWORD | Database password | my-secret-pw | Yes |
| DB_CHARSET | Database character set | utf8mb4 | Yes |
| SMTP_FROMNAME | Email from name | Service | Yes |
| SMTP_FROMADDRESS | Email from address | [email protected] | Yes |
| SMTP_HOST | Email server hostname | mail.aol.com | Yes |
| SMTP_PORT | Email server port | 587 | Yes |
| SMTP_USERNAME | Email server username | username | Yes |
| SMTP_PASSWORD | Email server pasword | password | Yes |
| SMTP_ENCRYPTION | Email server encryption | tls | Yes |
| LOG_ENABLE | Enable application logging | true | Yes |
- Pull the image and run the application:
docker-compose pull
docker-compose up -d- The application should now be running on http://localhost:8080.
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 mysql 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. Altough 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).
In order to manually install HortusFox you need to first setup a PHP environment along with a MySQL 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. Note: It is recommended to setup the actual production environment on, e.g., a home server. There are various solutions available for this.
composer installNow we need to configure the project. Create a .env file from the .env.example, open it and manage the following variables:
# Here you can set your default language. However users have the opportunity to set their personal language
APP_LANG="en"
# This is the name of the workspace, e.g. your home
APP_WORKSPACE="My home"
# This determines if the scroller shall be shown. It is useful to quickly (but smoothly) scroll to top
APP_ENABLESCROLLER=true
# Determines the amount of minutes that is used within the calculation of a users online status. You can leave it as is
APP_ONLINEMINUTELIMIT=5
# Use this setting if you want to show or hide the current online user list in the chat
APP_SHOWCHATONLINEUSERS=false
# Use this setting if you want to show or hide an indiactor if someone types a chat message
APP_SHOWCHATTYPINGINDICATOR=false
# The authentication token to be used to request cronjobs. Set this to a token of your choice
APP_CRONPW="your-auth-token"
# This must be set to true for the product to work in order to enable database connection
DB_ENABLE=true
# Enter your hostname or IP address of your MySQL database server
DB_HOST=localhost
# Enter the database username
DB_USER=root
# Enter the database user password
DB_PASSWORD=""
# Database connection port. Normally this doesn't need to be changed
DB_PORT=3306
# The actual database of your MySQL server to be used
DB_DATABASE=hortusfox
# Database driver. This needs to be unaltered for now
DB_DRIVER=mysql
# The name of the e-mail sender
SMTP_FROMNAME="Test"
# The e-mail address of the sender
SMTP_FROMADDRESS="[email protected]"
# Hostname or address to your SMTP mail provider
SMTP_HOST=""
# Port to be used for connecting to the host
SMTP_PORT=587
# Your SMTP username
SMTP_USERNAME=""
# Your SMTP password for authentication
SMTP_PASSWORD=""
# Communication encryption
SMTP_ENCRYPTION=tlsAfter saving the file you can now let the product create all neccessary tables via the following command:
php asatru migrate:freshNow you need to insert your initial app settings profile into the database. These settings can be later adjusted in the admin dashboard.
INSERT INTO `AppModel` (id, workspace, language, scroller, chat_enable, chat_timelimit, chat_showusers, chat_indicator, history_enable, history_name, enable_media_share, cronjob_pw, overlay_alpha, smtp_fromname, smtp_fromaddress, smtp_host, smtp_port, smtp_username, smtp_password, smtp_encryption, created_at) VALUES (
NULL,
'My workspace name',
'en',
1,
1,
5,
1,
0,
1,
'History',
0,
'a-secret-pw',
null,
'',
'',
'',
587,
'',
'',
'tls',
CURRENT_TIMESTAMP
)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:
php asatru serveNow 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:
INSERT INTO `users` (`id`, `name`, `email`, `password`, `password_reset`, `session`, `status`, `admin`, `lang`, `chatcolor`, `show_log`, `show_plants_aoru`, `notify_tasks_overdue`, `notify_tasks_tomorrow`, `last_seen_msg`, `last_typing`, `last_action`, `created_at`) VALUES
(
NULL,
'Username',
'[email protected]',
'your_password_token_here',
NULL,
NULL,
0,
1,
NULL,
NULL,
1,
1,
1,
1,
NULL,
NULL,
CURRENT_TIMESTAMP,
CURRENT_TIMESTAMP
);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:
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 will 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.
INSERT INTO `locations` (`id`, `name`, `icon`, `active`, `created_at`) VALUES
(
NULL,
'Name of location',
'fas fa-leaf',
1,
CURRENT_TIMESTAMP
);The mandatory fields are name of location (e.g. garden, living room, kitchen, etc) as well as the FontAwesome icon to be used. You can use all free FontAwesome icons (v5.15.4 free icons). For a complete list of available icons, visit the FontAwesome search page. Note that you can then manage various aspects of the system via the admin section when logged in as a user with admin privileges. Additionally you might want to build the android mobile app for your users.
Cronjobs are used to regularly execute a specific task. For each cronjob you need to set the cronjob parameter with your token set via AppModel.cronjob_pw. The following cronjobs are available:
# Used to inform users about overdue tasks. Should be called multiple times per day.
GET /cronjob/tasks/overdue?cronpw={your-auth-token}
# Used to inform users about tasks that are due tomorrow. Should be called multiple times per day.
GET /cronjob/tasks/tomorrow?cronpw={your-auth-token}- PHP ^8.2
- MySQL (10.4.27-MariaDB or similar)
- SMTP server for e-mailing
- Docker with Docker-Compose for containerization
Please view the contribution guidelines if you intend to contribute to our repository.