Bitnami GitLab for Google Cloud Platform

IMPORTANT: This documentation applies to Bitnami Gitlab Stack 8.16.3 or higher. If you have installed Bitnami Gitlab Stack 8.14.3 or earlier, please check the documentation of Bitnami Gitlab Legacy Stack.

Description

GitLab is self-hosted Git management software that's fast, secure, and based on Ruby on Rails. GitLab CI (also included) is an open-source Continuous Integration (CI) server closely integrated with Git and GitLab.

First steps with the Bitnami GitLab Stack

Welcome to your new Bitnami application running on Google Cloud Platform! Here are a few questions (and answers!) you might need when first starting with your application.

What is the administrator username set for me to log in to the application for the first time?

Username: root

What is the administrator password?

What SSH username should I use for secure shell access to my application?

SSH username: bitnami

How to connect to the PostgreSQL database?

You can connect to the PostgreSQL database using the default Omnibus GitLab configuration as follows:

  • As application user:

     $ sudo gitlab-rails dbconsole
    
  • As PostgreSQL superuser:

     $ sudo gitlab-psql -d gitlabhq_production
    

Find out how to obtain application credentials.

How to start or stop the servers?

To start, stop or restart GitLab and all its components you just need to run the gitlab-ctl command.

  • Start all GitLab components:

     $ sudo gitlab-ctl start
    
  • Stop all GitLab components:

     $ sudo gitlab-ctl stop
    
  • Restart all GitLab components:

     $ sudo gitlab-ctl restart
    

How to start or stop an individual component?

To start, stop or restart an individual component, just add the service you want to perform the action on it:

    $ sudo gitlab-ctl restart sidekiq

How to create a full backup of GitLab?

Creating a backup of omnibus-gitlab configuration

To prevent possible issues it is strongly recommended to keep a copy of the /etc/gitlab directory in a safe place. It is very important that you have, at least, a copy of these files:

  • /etc/gitlab/gitlab.rb: contains the configuration parameters of the application.

  • /etc/gitlab/gitlab-secrets.json: contains the database encryption keys to protect sensitive data in the SQL database.

NOTE: It is very important to store the files above in different places. Separating the configuration backup from the application backup reduces the chance of losing or having stolen both your encrypted application data and the keys needed to decrypt it.
  • To backup the configuration, you need to backup the /etc/gitlab directory:

     $ sudo sh -c 'umask 0077; tar -cf $(date "+etc-gitlab-%s.tar") -C / etc/gitlab'
    

Creating a GitLab system backup

To create a backup of a GitLab installation with the Omnibus package, run the following command:

$ sudo gitlab-rake gitlab:backup:create

This command will create a backup stored in the /var/opt/gitlab/backups directory.

Find more information about how to create a backup of GitLab in the official documentation.

Creating a daily backup

(Optional): you also can create a daily application backup following the steps above:

  • Edit the "cron table" for user root:

     $ sudo crontab -e -u root
    
  • Run the following command to create a compressed .tgz file of the /etc/gitlab directory (the example below shows a scheduled backup from Wednesday [day 3] to Sunday [day 7]):

     15 04 * * 3-7  umask 0077; tar cfz /secret/gitlab/backups/$(date "+etc-gitlab-\%s.tgz") -C / etc/gitlab
    

How to restore a backup of GitLab?

Restoring the Omnibus-GitLab configuration backup

Extract the .tar file you have obtained in the backup process as follows:

  • Rename the existing /etc/gitlab directory (in case it exists):

     $ sudo mv /etc/gitlab /etc/gitlab.$(date +%s)
    
  • Extract the files (the TIMESTAMP_NUMBER is a placeholder, your configuration backup has its own timestamp):

     $ sudo tar -xf etc-gitlab-TIMESTAMP_NUMBER.tar -C /
    
  • Run the following command to restore the configuration backup:

     $ sudo gitlab-ctl reconfigure
    
    NOTE: Your machine's SSH host keys are stored in a separate location at /etc/ssh/. Check these instructions to backup and restore those keys.

Restoring the GitLab system backup

NOTE: You can only restore a backup to exactly the same version of GitLab that you created it on (e.g.: 8.10).

These instructions assume that:

  • You have installed the same version of GitLab Omnibus as that used in your backup.

  • GitLab is running. If not, start it running the following command:

     $ sudo gitlab-ctl start
    

To restore the application backup follow the steps below:

  • Run the gitlab-ctl reconfigure command at least once, if you haven't done before:

     $ sudo gitlab-ctl reconfigure
    
  • Make sure that the backup .tgz or .tar file is in the backup directory. To find it, you can check in the /etc/gitlab/gitlab.rb file the following line gitlab_rails['backup_path']. It is located by default at /var/opt/gitlab/backups, if not, copy it into the default directory:

     $ sudo cp TIMESTAMP_NUMBER_YEAR_MONTH_DAY_gitlab_backup.tar /var/opt/gitlab/backups/
    

    Remember that TIMESTAMP_NUMBER_YEAR_MONTH_DAY is a placeholder. Your backup file should be like this: 1393513121_2017_02_04_gitlab_backup.tar

  • Stop only those processes that are connected to the database. Leave the rest running:

     $ sudo gitlab-ctl stop unicorn
     $ sudo gitlab-ctl stop sidekiq
    
  • Verify the status of those processes:

     $ sudo gitlab-ctl status
    
  • Restore the backup. You need to specify the timestamp of the backup you want to restore:

     $ sudo gitlab-rake gitlab:backup:restore BACKUP=TIMESTAMP_NUMBER_YEAR_MONTH_DAY
    
  • Restart and check GitLab:

     $ sudo gitlab-ctl start
     $ sudo gitlab-rake gitlab:check SANITIZE=true
    

How to configure outbound email settings?

Google Cloud Platform doesn't allow SMTP traffic through default ports: 25, 465, 587. Check Google cloud documentation to learn how to use a VPN to bypass these restrictions or use a different port for sending emails from your application.

  • Edit the parameters of the "GitLab email server settings" section in the /etc/gitlab/gitlab.rb configuration file to configure the SMTP settings. This is an example of how to configure the email settings using a Gmail account. Replace USERNAME and PASSWORD with your Gmail account username and password respectively.

     gitlab_rails['smtp_enable'] = true
     gitlab_rails['smtp_address'] = "smtp.gmail.com"
     gitlab_rails['smtp_port'] = 587
     gitlab_rails['smtp_user_name'] = "USERNAME@gmail.com"
     gitlab_rails['smtp_password'] = "PASSWORD"
     gitlab_rails['smtp_domain'] = "smtp.gmail.com"
     gitlab_rails['smtp_authentication'] = "login"
     gitlab_rails['smtp_enable_starttls_auto'] = true
     gitlab_rails['smtp_tls'] = false
     gitlab_rails['smtp_openssl_verify_mode'] = 'peer' 
    

Check the GitLab official documentation to get more examples.

  • Run the following command to have the changes take effect:

     $ sudo gitlab-ctl reconfigure
    
  • Test if GitLab sends emails properly using the Rails console by executing the following commands. Replace USERNAME with your Gmail account username.

     $ gitlab-rails console
     $ irb(main):003:0> Notify.test_email('USERNAME@gmail.com', 'Message Subject', 'Message Body').deliver_now
    

To configure the application to use other third-party SMTP services for outgoing email, such as SendGrid or Mandrill, refer to the FAQ.

If you are using Gmail as the outbound email server and you are not receiving emails correctly, make sure that the Google "Allow less secure apps" option is activated. To do so:

Allow less secure apps in Gmail

How to upload files to the server with SFTP?

Although you can use any SFTP/SCP client to transfer files to your server, the link below explains how to configure FileZilla (Windows, Linux and Mac OS X), WinSCP (Windows) and Cyberduck (Mac OS X). It is required to use your server's private SSH key to configure the SFTP client properly. Choose your preferred application and follow the steps in the link below to connect to the server through SFTP.

How to upload files to the server

How to change the default address for GitLab?

Changing the default address automatically

It is advisable to use a host name instead of an IP address for Gitlab. However, we recommend not using git. in the host name as this causes problems when accessing Gitlab over HTTP.

Follow these steps:

  • At the server console, run the following command:

     $ sudo /opt/bitnami/apps/gitlab/bnconfig --machine_hostname NAME
    
    IMPORTANT: If you've configured GitLab to use a static domain name, remove or rename the /opt/bitnami/apps/gitlab/bnconfig file to avoid it being reset on the next system reboot. Read more about this tool.

Changing the default address manually for GitLab

To configure an external URL for GitLab, modify the external_url parameter in the /etc/gitlab/gitlab.rb file:

external_url "https://gitlab.example.com"
  • Run the gitlab-ctl script to apply the changes as follows:

     $ sudo gitlab-ctl reconfigure
    

How to create an SSL certificate?

You can create your own SSL certificate with the OpenSSL binary. A certificate request can then be sent to a certificate authority (CA) to get it signed into a certificate, or if you have your own certificate authority, you may sign it yourself, or you can use a self-signed certificate (because you just want a test certificate or because you are setting up your own CA).

NOTE: The current Bitnami GitLab installation already includes the server.key and the server.crt certificates. It is strongly recommended to back up these files before create a new ones. Run the following commands to make sure that you save a copy of the current self-signed certificates:

   $ sudo mv /etc/gitlab/ssl/server.crt /etc/gitlab/ssl/server.crt.back
   $ sudo mv /etc/gitlab/ssl/server.key /etc/gitlab/ssl/server.key.back
  • Create your private key:

     $ sudo openssl genrsa -out /etc/gitlab/ssl/conf/server.key 2048
    
  • Create a certificate:

     $ sudo openssl req -new -key /etc/gitlab/ssl/server.key -out  /etc/gitlab/ssl/cert.csr
    
    IMPORTANT: Enter the server domain name when the above command asks for the "Common Name".
  • Send cert.csr to the certificate authority. When the certificate authority completes their checks (and probably received payment from you), they will hand over your new certificate to you.

  • Until the certificate is received, create a temporary self-signed certificate:

     $ sudo openssl x509 -in  /etc/gitlab/ssl/cert.csr -out  /etc/gitlab/ssl/server.crt -req -signkey  /etc/gitlab/ssl/server.key -days 365
    
  • Back up your private key in a safe location after generating a password-protected version as follows:

     $ sudo openssl rsa -des3 -in  /etc/gitlab/ssl/server.key -out privkey.pem
    

Note that if you use this encrypted key in the configuration file, GitLab won't be able to start Nginx after any gitlab-ctl reconfigure command. Regenerate the key without password protection from this file as follows:

    $ sudo openssl rsa -in privkey.pem -out  /etc/gitlab/ssl/server.key

Find more information about certificates at http://www.openssl.org.

How to debug Gitlab errors?

To debug Gitlab errors, check the following files depending on the issue:

  • Gitlab log: the Gitlab log is at /opt/gitlab/embedded/service/gitlab-rails/log/production.log.

  • Sidekiq log: check it if the Sidekiq server cannot be started at /var/log/gitlab/gitlab-rails/sidekiq.log.

  • Gitlab-shell log: the Gitlab-shell log is at /var/log/gitlab/gitlab-shell/gitlab-shell.log.

For more information about Gitlab errors, visit the GitLab official documentation.

How to debug Nginx errors?

Check the Nginx log file at /var/log/gitlab/nginx/gitlab_error.log.

How to enable HTTPS support with SSL certificates?

Important considerations

NOTE: The steps below assume that you are using a custom domain name and that you have already configured the custom domain name to point to your cloud server. See more details in the How to change the default address for GitLab? section.
  • By enabling HTTPS you must provide a secure connection to your instance for at least the next 24 months. Nginx configuration will tell browsers and clients to communicate with your GitLab instance only over a secure connection for this period.

Bitnami images come with SSL support already pre-configured and with a dummy certificate in place which is fine for testing and development purposes. To use a valid SSL certificate for production select one of these options:

Activate SSL support

Once you obtain the certificate and certificate key files, you will need to update your server to use them. Follow these steps to activate SSL support:

  • Use the table below to identify the correct locations for your certificate and configuration files.

    Variable Value
    Current application URL https://[custom-domain]/
      Example: https://my-domain.com/ or https://my-domain.com/appname
    GitLab configuration file /etc/gitlab/gitlab.rb
    Certificate file /etc/gitlab/ssl/server.crt
    Certificate key file /etc/gitlab/ssl/server.key
  • Copy your SSL certificate and certificate key file to the specified locations.

  • Once you have copied all the server certificate files, you may make them readable by the root user only with the following commands:

     $ sudo chown root:root /etc/gitlab/ssl/
     $ sudo chmod 600 /etc/gitlab/ssl/
    
  • Run the following command to have the activation take effect:

     $ sudo gitlab-ctl reconfigure
    

Find more information about certificates at the GitLab official documentation.

How to push your changes to the GitLab application?

Once you have uploaded your public key to Gitlab, you can upload your repository to the application. These are the basic steps:

$ git config --global user.name "Your full name"
$ git config --global user.email "user@example.com"
$ git checkout master
$ git remote add origin git@SERVER-IP:test/test.git
$ git push -u origin master

How to run rake commands?

To run rake commands, use the gitlab-rake script located inside the /opt/gitlab/bin/ directory.

$ sudo gitlab-rake gitlab:check

Troubleshooting

Check GitLab troubleshooting documentation for more information about GitLab issues.

How to upgrade GitLab?

If you have already installed Omnibus GitLab, the GitLab official repository is has been configured for you. In case you aren't using GitLab official repositories for any reason, you can also manually update the application by downloading the official packages.

Learn how to update GitLab.

How to use your .pem file to pull or push?

You can use your server .pem file instead of creating a new key pair.

  • Get your .pem public key, by running the following command:

       $ ssh-keygen -y -f KEYFILE
    
  • Add this key to Gitlab using the application API.

  • Edit (or create if not exists) ~/.ssh/config and add the following lines, replacing SERVER-IP with the IP address or domain name of the GitLab server if necessary and KEYFILE with the full path to the .pem file.

       Host SERVER-IP 
       IdentityFile KEYFILE