1. This guide requires that you have a clean **Debian 7.7 x64** or **Ubuntu 14.04 x64** installation with administrative rights. We have tested the installation guide on a Debian minimal netinstall image and on an Ubuntu Server image, but it should work on any derivative.
2. OpenProject will be installed with a MySQL database (the guide should work analogous with PostgreSQL).
3. OpenProject will be served in a production environment with Apache (this guide should work analogous with other servers, like nginx and others)
In this guide, we will install **OpenProject 4.1** with a **MySQL** database. Openproject will be served with the **Apache** web server. When your server needs to reboot, OpenProject should start automatically with your server.
Note: We have highlighted commands to execute like this
```bash
[user@host] command
```
Where the `user` is the operating system user the command is executed with. The `host` is either `debian` (when the command is Debian-specific), `ubuntu` (when the command is Ubuntu-specific), or `all` (when the command shall be executed on either operating system).
If you find any bugs or you have any recommendations for improving this tutorial, please, feel free to create a pull request against this guide.
## Prepare Your Environment
Install tools needed to compile Ruby and run OpenProject:
It can be that curl fails to download the RVM source, because of the missing GPG key. If that is the case, download the key (as suggested in the error message):
Now, edit the `configuration.yml` file as you like.
```ruby
production: #main level
email_delivery_method: :smtp #settings for the production environment
smtp_address: smtp.gmail.com
smtp_port: 587
smtp_domain: smtp.gmail.com
smtp_user_name: ***@gmail.com
smtp_password: ****
smtp_enable_starttls_auto: true
smtp_authentication: plain
```
Add this line into `configuration.yml` file at the of of file for better performance of OpenProject:
```ruby
rails_cache_store: :memcache
```
**NOTE:** You should validate your .yml-files, for example with http://www.yamllint.com/. Both, the `database.yml` and `configuration.yml` file are sensitive to whitespace. It is pretty easy to write invalid .yml files without seeing the error. Validating those files prevents you from such errors.
The passenger installer will ask you the question in "Which languages are you interested in?". We are interested only in ruby.
As told by the installer, add this lines to `/etc/apache2/apache2.conf`.
But before copy&pasting the following lines, check if the content (especially the version numbers!) is the same as the `passenger-install-apache2-module` installer said. When you're in doubt, do what passenger tells you.
The passenger installer will ask you the question in "Which languages are you interested in?". We are interested only in ruby.
The passenger installer tells us to edit the apache config files. To do this, continue as the root user:
```bash
[openproject@ubuntu] exit
```
As told by the installer, create the file `/etc/apache2/mods-available/passenger.load` and add the following line.
But before copy&pasting the following lines, check if the content (especially the version numbers!) is the same as the `passenger-install-apache2-module` installer said. When you're in doubt, do what passenger tells you.
As the root user, create the file `/etc/apache2/sites-available/openproject.conf` with the following contents:
```apache
<VirtualHost*:80>
ServerName www.myopenprojectsite.com
# !!! Be sure to point DocumentRoot to 'public'!
DocumentRoot /home/openproject/openproject/public
<Directory/home/openproject/openproject/public>
# This relaxes Apache security settings.
AllowOverride all
# MultiViews must be turned off.
Options -MultiViews
# Uncomment this if you're on Apache >= 2.4:
Require all granted
</Directory>
</VirtualHost>
```
Let's enable our new `openproject` site (and disable the default site, if necessary)
```bash
[root@ubuntu] a2dissite 000-default
[root@ubuntu] a2ensite openproject
```
### Debian and Ubuntu
Now, we (re-)start Apache:
```bash
[root@all] service apache2 reload
```
Your OpenProject installation should be accessible on port 80 (http). A default admin-account is created for you having the following credentials:
```bash
Username: admin
Password: admin
```
Please, change the password on the first login. Also, we highly recommend to configure the SSL module in Apache for https communication.
## Activate Background Jobs
OpenProject sends (some) mails asynchronously by using background jobs. All such jobs are collected in a queue, so that a separate process can work on them. This means that we have to start the background worker. To automate this, we put the background worker into a cronjob.
```bash
[root@all] su - openproject -c "bash -l"
[openproject@all] crontab -e
```
Now, the crontab file opens in the standard editor. Add the following entry to the file:
* Watch for OpenProject updates. We advise to always run the latest stable version of OpenProject (especially for security updates). Information on how to perform an update can been found in the [upgrade guide](upgrade-guide.md). You can find out about new OpenProject releases in our [news](https://community.openproject.org/projects/openproject/news), or on [twitter](https://twitter.com/openproject).
For general information and a list of all plug-ins known to us, refer to to the [plug-in page](https://community.openproject.org/projects/openproject/wiki/OpenProject_Plug-Ins).
OpenProject plug-ins are separated in ruby gems. You can install them by listing them in a file called `Gemfile.plugin`. An example `Gemfile.plugin` file looks like this:
The next web-request to the server will take longer (as the application is restarted). All subsequent request should be as fast as always.
We encourage you to extend OpenProject yourself by writing a plug-in. Please, read the [plugin-contributions](https://community.openproject.org/projects/openproject/wiki/Developing_Plugins) guide for more information.
* **I followed the installation guide faithfully and OpenProject is running. Now, how do I log in?**
The `db:seed` command listed above creates a default admin-user. The username is `admin` and the default password is `admin`. You are forced to change the admin password on the first login.
If you cannot login as the admin user, make sure that you have executed the `db:seed` command.
* **I cannot solve an error, not even with the log files. How do I get help?**
You can find help in [the OpenProject forums](https://community.openproject.org/projects/openproject/boards). Please tell us, if possible, what you have done (e.g. which guide you have used to install OpenProject), how to reproduce the error, and provide the appropriate error logs.
It often helps to have a look at the already answered questions, or to search the Internet for the error. Most likely someone else has already solved the same problem.
* **I get errors, since I have installed an OpenProject plug-in**
With each new OpenProject core version, the plug-ins might need to be updated. Please make sure that the plug-in versions of all you plug-ins works with the OpenProject version you use.
Many plug-ins follow the OpenProject version with their version number (So, if you have installed OpenProject version 4.1.0, the plug-in should also have the version 4.1.0).
If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the appropriate community [forum](https://community.openproject.org/projects/openproject/boards/9).
[Follow OpenProject on twitter](https://twitter.com/openproject), and follow the news on [openproject.org](http://openproject.org) to stay up to date.
