diff options
Diffstat (limited to 'doc/administration/package_information/omnibus_packages.md')
| -rw-r--r-- | doc/administration/package_information/omnibus_packages.md | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md new file mode 100644 index 00000000000..aa73534fc55 --- /dev/null +++ b/doc/administration/package_information/omnibus_packages.md @@ -0,0 +1,115 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Omnibus based packages and images + +Below you can find some basic information on why GitLab provides packages and +a Docker image that come with bundled dependencies. + +These methods are great for physical and virtual machine installations, and simple Docker installations. + +## Goals + +We have a few core goals with these packages: + +1. Extremely easy to install, upgrade, maintain. +1. Support for a wide variety of operating systems +1. Wide support of cloud service providers + +## Omnibus GitLab Architecture + +GitLab in its core is a Ruby on Rails project. However, GitLab as a whole +application is more complex and has multiple components. If these components are +not present or are incorrectly configured, GitLab will not work or it will work +unpredictably. + +The [GitLab Architecture Overview](../../development/architecture.md#gitlab-architecture-overview) shows some of these components and how they +interact. Each of these components needs to be configured and kept up to date. + +Most of the components also have external dependencies. For example, the Rails +application depends on a number of [Ruby gems](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/Gemfile.lock). Some of these dependencies also +have their own external dependencies which need to be present on the Operating +System in order for them to function correctly. + +Furthermore, GitLab has a monthly release cycle requiring frequent maintenance +to stay up to date. + +All the things listed above present a challenge for the user maintaining the GitLab +installation. + +## External Software Dependencies + +For applications such as GitLab, external dependencies usually bring the following +challenges: + +- Keeping versions in sync between direct and indirect dependencies +- Availability of a version on a specific Operating System +- Version changes can introduce or remove previously used configuration +- Security implications when library is marked as vulnerable but does not have + a new version released yet + +Keep in mind that if a dependency exists on your Operating System, it does not +necessarily exist on other supported OSs. + +## Benefits + +A few benefits of a package with bundled dependencies: + +1. Minimal effort required to install GitLab. +1. Minimum configuration required to get GitLab up and running. +1. Minimum effort required to upgrade between GitLab versions. +1. Multiple platforms supported. +1. Maintenance on older platforms is greatly simplified. +1. Less effort to support potential issues. + +## Drawbacks + +Some drawbacks of a package with bundled dependencies: + +1. Duplication with possibly existing software. +1. Less flexibility in configuration. + +## Why would I install an omnibus package when I can use a system package? + +The answer can be simplified to: less maintenance required. Instead of handling +multiple packages that *can* break existing functionality if the versions are +not compatible, only handle one. + +Multiple packages require correct configuration in multiple locations. +Keeping configuration in sync can be error prone. + +If you have the skill set to maintain all current dependencies and enough time +to handle any future dependencies that might get introduced, the above listed +reasons might not be good enough for you to not use the omnibus package. + +There are two things to keep in mind before going down this route: + +1. Getting support for any problems + you encounter might be more difficult due to the number of possibilities that exist + when using a library version that is not tested by majority of users. +1. Omnibus package also allows shutting off of any services that you do not need, + if you need to run a component independently. For example, you can use a + [non-bundled PostgreSQL database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server) with the omnibus package. + +Keep in mind that a non-standard solution like the omnibus package +might be a better fit when the application has a number of moving parts. + +## Docker image with multiple services + +[GitLab Docker image](../../install/docker.md#gitlab-docker-images) is based on the omnibus package. + +Considering that container spawned from this image contains multiple processes, +these types of containers are also referred to as 'fat containers'. + +There are reasons for and against an image like this, but they are similar to +what was noted above: + +1. Very simple to get started. +1. Upgrading to the latest version is extremely simple. +1. Running separate services in multiple containers and keeping them running + can be more complex and might not be required for a given install. + +This method is useful for organizations just getting started with containers and schedulers, and may not be ready for a more complex installation. This method is a great introduction, and will work well for smaller organizations. |