Easy virtual machine (VM)
This documentation is for virtual machines (VM) provided by Easy Software for Clients who bought Server solution. It is valid for VMs generated after March 1st 2022.
It may also serve as inspiration of your own server environment, but in such case there are no guarantees due to the variety of possible components and technologies you may be using.
The VM is configured just for small sites (cca 10 simultanously working users). VM is almost production ready but REQUIRES experienced administrator to install VM in your environment, set up backuping, monitoring, networking, security policies etc. Easy Software can not take responsibility for running of this VM in your dedicated environment, the VM is an example how the application can be hosted.
This README addresses "Application", which can be substituted by either "Easy Project" or "Easy Redmine".
Because the VM was generated at a certain point in time, it is possible that some components may have already released some patches or security fixes by the time you are deploying it.
That is why you should always start with a backup followed by update of the OS. It will install the latest security fixes and update possibly outdated components.
OS is Debian in 64-bit edition.
The important defaults are:
- OS is available by SSH via port 22
- Firewall is not set (it is up to system administrators)
- The data disk is small as a 5GB (mountpoint is /home)
- Application listens on HTTPS but with self-signed certificate, so you have to replace it ASAP (more details below)
- Application is running in /home/easy/[application_name]/current.
- username: easy
- password: e4syPwd-
Please change it ASAP. To do so run command passwd in terminal
Simply use command mysql your_app_name (all dots or dashes in application name should be replaced with underlines. Example: your-app-name should be your_app_name)
Default login (in case of "clean" database) is
- username: admin
- password: admin
In case of database from your Cloud application, passwords remain as you had them.
Structure of the application's home
├── backups # backup script save data there
├── application.sock # nginx uses this socket
│ ├── # pregenerated application configurations
│ ├── # (database, mailing, secrets, app server, etc...)
│ └── ...
│ ├── config # all application configurations
│ │ ├── configuration.yml # set up outgoing mail configuration here
│ │ ├── database.yml # database access configured here
│ │ └── ...
│ ├── files # persistent application data
│ ├── log # application logs
│ ├── public # static files
│ └── version # application version
└── public_html -> /home/easy/$APP_NAME/current
Restarting the application is simply via "systemctl restart puma@[application_name]" as sudo
The VM runs on the latest recomended version of Debian. The system requires common maintenance like:
- regular updates
- resource monitoring (free space, memory usage, load, ...)
- data backups to an independent disk
- security policies
Do security updates of the system frequently. We recommend to do it at least once per week. Before update please be sure that latest backup is available and working.
Official documentation how to run only security updates https://wiki.debian.org/UnattendedUpgrades
Easy Software has good experience with Prometheus. Therefore, the node_exporter is a part of the VM since the 1.3. 2022.
The official very basic documentation for Node Exporter and Prometheus is at https://prometheus.io/docs/guides/node-exporter/ The best quickstart grafana dashboard is at https://grafana.com/grafana/dashboards/1860
Depending on your usage you should tune the VM resource settings, for example increase amount of RAM or number of cores provided to VM. All these configurations should be regularly done by your virtual environment administrator.
Node exporter listens on port 9100.
node_exporter could by disabled by running:
systemctl stop node_exporter.service
systemctl disable node_exporter.service
systemctl mask node_exporter.service
It prevents to start node exporter after next reboot...
If you need full environment support from Easy Software (security and performance optimizations, backuping, monitoring, etc), we recommend to transfer to our Cloud solutions.
The preconfigured backuping that is present in the VM is a working example, that needs to be fit to your infrastructure and has to be monitored. Please keep in mind, that a proper backup should be:
- checked after backup process finished (check at least the size of the backup)
- kept in a safe place
- distant from the running environment (at least in a different city)
- restored once in a while to test your ability to perform recovery
The application stores data in two places, so don't forget to backup both of them.
Database backup can be very easily done incorrectly. The best and the most secure way how to do backups of mysql database is via database dump as you can see in the example script. It makes version independent backups, that could be restored whole or allows you to get only part of the old data.
mysqldump --add-drop-tables --routines --triggers --flush-logs $DATABASE_NAME > path/to/file_where_db_will_be_stored.sql
Copying files from /var/lib/mysql is an INCORRECT way of saving DB backups.
Every uploaded file/attachment in the application is stored in /home/easy/$APP_NAME/current/files. The whole content of this directory should be backed up. In this case, you can simply copy the contents.
The VM contains SSH keys for Easy Software engineers in home/easy/.ssh/authorized_keys. Also, the rules for the iptables firewall in /etc/iptables allow access of an Easy Software IP address.
Both of these policies are meant for eventual remote support by our staff on your request. The access policies are fully under your control.
All automatic tasks are scheduled by CRON and Sidekiq, which starts scheduled jobs every 5m. We recommend don't to run these jobs in shorter intervals due to their high performance requirements. To make any changes, you can edit them by running command below under user easy
Migrate data to this VM
How to import older Application or Redmine data (SOURCE) into VM (TARGET). This works in most cases, but this procedure may not work in case you use 3rd party plugins in your source Redmine instance.
1. from your (SOURCE) create MySQL dump file:
mysqldump --opt easy > backup.sql
2. transfer backup.sql into (TARGET)
3. go to Application folder on (TARGET)
4. recreate (TARGET) database
bundle exec rake db:drop db:create RAILS_ENV=production DISABLE_DATABASE_ENVIRONMENT_CHECK=1
5. import backup.sql
mysql [db_name] < backup.sql
6. transfer attachments and other files from (SOURCE)[redmine]/files into (TARGET)/home/easy/[application_name]/current/files
bundle exec rake easyproject:install RAILS_ENV=production
8. restart application
sudo systemctl restart puma@[application_name]
On some of the machines sidekiq@.service file is not added. Please check /etc/systemd/system folder if sidekiq@.service file is presented. If not - please add it. It should contain the next:
Description=SIDEKIQ service for %i
ExecStart=/usr/local/rvm/bin/rvm default do bundle exec sidekiq -e production
ExecReload=/bin/kill -s TSTP $MAINPID
WantedBy=multi-user.target puma@%i.service unicorn@%i.service
After file is created run
sudo systemctl daemon-reload
MYSQL Backups are targeted to wrong database
To fix this issue please open file /usr/local/bin/mysql-backups.sh and replace DB name "easy" to app DB (usually it's the same as app name but all dashes and dots should be replaced with underlines)