Gitlab Installation Using an External Database

How to install Gitlab while using an external PostgreSQL database.

Gitlab Installation Using an External Database


This post highlights how to install Gitlab while using an external PostgreSQL database. While Gitlab comes with a prepackaged installation of PostgreSQL, it is convenient to manage and use an existing database outside of the local hosts system.


I was attempting to install Gitlab on a Proxmox virtualized container. I ran into major issues with the maintained packages in the Ubuntu and Debian repositories. The package in the Debian based repositories utilizes dbconfig to create and manage the database. No matter how I set the configuration during installation, I noticed that dbconfig would always default back to using the local database and fail with the following error:

psql: FATAL: database "gitlab_production" does not exist

Save yourself the trouble and install Gitlab using the official Omnibus installation method.


Follow the standard Omnibus installation guide up until the point of performing the gitlab-ctl reconfigure. At this point, create a database superuser on the external database to use for gitlab:

createuser -s gitlab

On the gitlab host, edit /etc/gitlab/gitlab.rb and set the following:

postgresql['enable'] = false
gitlab_rails['db_adapter'] = "postgresql"
gitlab_rails['db_encoding'] = "unicode"
gitlab_rails['db_database'] = "gitlab_production"
gitlab_rails['db_username'] = "gitlab"
gitlab_rails['db_password'] = "password"
gitlab_rails['db_host'] = "ip_address"

These settings disable the prepackaged Postgres database, and configures the Gitlab to use the external database. Now you can continue the installation by issueing gitlab-ctl reconfigure and gitlab-rake gitlab:setup to seed the external database.