We support integration with the Apache webserver to create and serve repositories on the fly along with contributions to the fine-grained project authorization system of OpenProject.
Using the default configuration, OpenProject allows you to *link* existing Subversion and Git repositories from the local filesystem (For Subversion, you can also integrate repositories from other servers using basic auth credentials).
This functionality is extended with managed repositories, whose life spans are actively controlled by OpenProject. You can explicitly create local repositories for a project and configure repository access using permission the existing access-control functionality on a per-project level.
## Managed Repositories
You can create repositories explicitly on the filesystem using *managed* repositories.
Managed repositories need to be enabled manually for each SCM vendor individually using the `configuration.yml`.
It contains a YAML configuration section for repository management residing under the namespace `scm`.
The following is an excerpt of the configuration and contains all required information to set up your data.
# Configuration of Source control vendors
# client_command:
# Use this command to the default SCM vendor command (taken from path).
# Absolute path (e.g. /usr/local/bin/hg) or command name (e.g. hg.exe, bzr.exe)
# On Windows, *.cmd, *.bat (e.g. hg.cmd, bzr.bat) does not work.
# manages:
# You may either specify a local path on the filesystem or an absolute URL to call when
# repositories are to be created or deleted.
# This allows OpenProject to take control over the given path to create and delete repositories
# directly when created in the frontend.
#
# When entering a URL, OpenProject will POST to this resource when repositories are created
# using the following JSON-encoded payload:
# - action: The action to perform (create, delete)
# - identifier: The repository identifier name
# - vendor: The SCM vendor of the repository to create
# - project: identifier, name and ID of the associated project
# - old_identifier: The identifier to the old repository (used only during relocate)
#
# NOTE: Disabling :managed repositories using disabled_types takes precedence over this setting.
#
# disabled_types:
# Disable specific repository types for this particular vendor. This allows
# to restrict the available choices a project administrator has for creating repositories
# See the example below for available types
#
# Available types for git:
# - :local (Local repositories, registered using a local path)
# - :managed (Managed repositores, available IF :manages path is set below)
# Available types for subversion:
# - :existing (Existing subversion repositories by URL - local using file:/// or remote
# using one of the supported URL schemes (e.g., https://, svn+ssh:// )
# - :managed (Managed repositores, available IF :manages path is set below)
#
# Examplary configuration (Enables managed Git repositories at the given path)
scm:
git:
manages: /srv/repositories/git
With this configuration, you can create managed repositories by selecting the `managed` Git repository in the Project repository settings tab.
### Reposman.rb
Part of the managed repositories functionality was previously provided with reposman.rb.
Reposman periodically checked for new projects and automatically created a repository of a given type.
It never deleted repositories on the filesystem when their associated project was removed in OpenProject.
This script has been integrated into OpenProject and extended. For further guidance on how to migrate to managed repositories, please see the [upgrade guide to 5.0](../operations/upgrading)
To enable remote managed repositories, pass an absolute URL to the `manages` key of a vendor in the `configuration.yml`. The following excerpt shows that configuration for Subversion, assuming your callback is `https://example.org/repos`.
When the response is successful, it must at least return a `url` property that contains an accessible URL and optionally a `path` property to access the repository locally.
*Note* that for Git repositories, OpenProject currently can only read them locally (i.e, through an NFS mount), so a path is mandatory here.
Our main use-cases for this feature is to elimnate the complexity associated with permission issues around Subversion mainly in packager, for which a simple Apache wrapper script is used in `extra/Apache/OpenProjectRepoman.pm`.
This functionality is very limited but may be extended when other use cases arise.
It supports notifications for creating repositories (action `create`), moving repositories (action `relocate`, when a project's identifier has changed), and deleting repositories (action `delete`).
If you're interested in setting up the integration manually outside the context of packager, the following excerpt will help you:
* This checkout instruction contains the checkout URL for the given repository and some further information on how the checkout works for this particular vendor (e.g., Subversion → svn checkout, Git → git clone).
* The instructions contain information regarding the capabilities a user has (read, read-write)
* The instructions are defined by the SCM vendor implementations themselves, so that the checkout instructions could be extended by some 3rd party SCM vendor plugin
The total required disk space for a project's its repository and attachments are listed in the projects administration pane, as well as the project setting overview.
This information is refreshed in the same manner that changesets are retrieved: By default, the repository is refreshed when a user visits the repository page. This information is cached for the time configured under the global `administration settings → repositories`.
It could also externally be refreshed by using a cron job using the Sys API. Executing a GET against `/sys/projects/:identifier/repository/update_storage` will cause a refresh when the maximum cache time is expired. If you pass the query `?force=1` to the request above, it will ignore the cache.
For a future release, we are hoping to provide a webhook to update changesets and storage immediately after a change has been committed to the repository.
# Accessing repositories through Apache
With managed repositories, OpenProject takes care of the lifetime of repositories and their association with projects, however we still need to serve the repositories to the client.
In the remainder of this document, we assume that you run OpenProject using a separate process, which listens for requests on http://localhost:3000 that you serve over Apache using a proxy.
On that page, enable *"Enable repository management web service"* and generate an API key (do not
forget to save the settings). We need that API key later in our Apache configuration.
You also need a distinct filesystem path for Subversion and Git repositories.
In this guide, we assume that you put your svn repositories in /srv/openproject/svn and your git repositories in /srv/openproject/git .
## Subversion Integration
Apache provides the module `mod_dav_svn` to serve Subversion repositories through HTTP(s).
This method requires some apache modules to be enabled and installed. The following commands are required for Debian / Ubuntu, please adjust accordingly for other distributions:
**Important:** If Apache and OpenProject run under separate users, you need to ensure OpenProject remains the owner of the repository in order to browse and delete it, when requsted through the user interface.
Due to the implementation of `mod_svn`, we have no way to influence the permissions determined by apache when changing repositories (i.e., by committing changes).
Without correcting the permissions, the following situation will occur:
* The run user of OpenProject can correctly create and manage repository under the managed path with appropriate permissions set
* As soon as a user checks out the repository and commits new data
* Apache alters and adds files to the repository on the server, now owned by the apache user its default umask.
* If the user decides to delete the repository through the frontend
* Altered files are not / no longer owned or writable by the OpenProject user
* The deletion fails
The following workarounds exist:
#### Apache running `mod_dav_svn` and OpenProject must be run with the same user
This is a simple solution, but theoretically less secure when the server provides more than just SVN and OpenProject.
#### Use Filesystem ACLs
You can define ACLs on the managed repository root (requires compatible FS).
You'll need the the `acl` package and define the ACL.
Assuming the following situation:
* Apache run user / group: `www-data`
* OpenProject run user: `openproject`
* Repository path for SCM vendor X: `/srv/repositories/X`
On many file systems, ACLS are enabled by default. On others, you might need to remount affected filesystems with the `acl` option set.
Note that this issue applies to mod_dav_svn only.
### Use the Apache wrapper script
Similar to the integration we use ourselves for the packager-based installation, you can set up Apache to manage repositories using the remote hook in OpenProject.
For more information, see the section 'Managing Repositories Remotely'.
### Exemplary Apache Configuration
We provide an example apache configuration. Some details are explained inline as comments.
# Load OpenProject per module used to authenticate requests against the user database.
# Be sure that the OpenProjectAuthentication.pm script is located in your perl path.
PerlSwitches -I/srv/www/perl-lib -T
PerlLoadModule Apache::OpenProjectAuthentication
<VirtualHost*:80>
ErrorLog /var/log/apache2/error
# The /sys endpoint is an internal API used to authenticate repository
# access requests. It shall not be reachable from remote.
<LocationMatch"/sys">
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
</LocationMatch>
# This fixes COPY for webdav over https
RequestHeader edit Destination ^https: http: early
# Serves svn repositories locates in /srv/openproject/svn via WebDAV
# It is secure with basic auth against the OpenProject user database.
# Note that the ProxyPass with the longest path should be listed first, otherwise
# a shorter path may match and will do an early redirect (without looking for other
# more specific matching paths).
ProxyPass /svn !
ProxyPass / http://127.0.0.1:3000/
ProxyPassReverse / http://127.0.0.1:3000/
</Location>
## Git Integration
We can exploit git-http-backend to serve Git repositories through HTTP(s) with Apache.
This method additionally requires the `cgi` Apache module to be installed. The following commands are required for Debian / Ubuntu, please adjust accordingly for other distributions:
<pre>
apt-get install git libapache2-mod-perl2
a2enmod proxy proxy_http cgi
</pre>
You need to locate the location of the `git-http-backend` CGI wrapper shipping with the Git installation.
Depending on your installation, it may reside in `/usr/libexec/git-core/git-http-backend`.
[More information on git-http-backend.](http://git-scm.com/docs/git-http-backend)
### Permissions
We create bare Git repositories in OpenProject with the [`--shared`](https://www.kernel.org/pub/software/scm/git/docs/git-init.html) option of `git-init` set to group-writable.
Thus, if you use a separate user for Apache and OpenProject, they need to reside in a common group that is used for repository management. That group must be set in the `configuration.yml` (see above).
### Exemplary Apache Configuration
We provide an example apache configuration. Some details are explained inline as comments.
# Load OpenProject per module used to authenticate requests against the user database.
# Be sure that the OpenProjectAuthentication.pm script is located in your perl path.
PerlSwitches -I/srv/www/perl-lib -T
PerlLoadModule Apache::OpenProjectAuthentication
<VirtualHost*:80>
ErrorLog /var/log/apache2/error
# The /sys endpoint is an internal API used to authenticate repository
# access requests. It shall not be reachable from remote.
<LocationMatch"/sys">
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
</LocationMatch>
# This fixes COPY for webdav over https
RequestHeader edit Destination ^https: http: early
# Serves svn repositories locates in /srv/openproject/svn via WebDAV
# It is secure with basic auth against the OpenProject user database.
# Note that the ProxyPass with the longest path should be listed first, otherwise
# a shorter path may match and will do an early redirect (without looking for other
# more specific matching paths).
ProxyPass /svn !
ProxyPass /git !
ProxyPass / http://127.0.0.1:3000/
ProxyPassReverse / http://127.0.0.1:3000/
</VirtualHost>
## Other integrations
With OpenProject 5.0, the interface to create custom integrations for other SCM vendors was improved dramatically.
If you're interested in writing a custom integration for some other SCM vendor (such as Mercurial), feel free to contact the developers of OpenProject over Github.
One examplary integration is the Gitolite plugin, which serves Git repositories from OpenProject over SSH using [Gitolite](http://www.gitolite.com).
The plugin is available at https://github.com/oliverguenther/openproject-revisions_git.
