Description

GitLab CE is an open source, cloud-based Git repository and version control system. Its built-in CI/CD integrates with existing processes and helps teams deliver high-quality code.

First steps with the Bitnami GitLab CE Stack

Welcome to your new Bitnami application! This guide includes some basic information you will need to get started with your application.

How to import a Bitnami Virtual Machine?

Check the following instructions to import a Bitnami Virtual Machine:

Importing a Bitnami Virtual Machine in VirtualBox

• Select the "File -> Import Appliance" menu option and select the .ova file downloaded from the Bitnami website. Then click "Continue".
• Once it is imported, click the "Start" button in the VirtualBox toolbar.

For a detailed walkthrough, check our Virtualbox tutorial.

Importing a Bitnami Virtual Machine in a VMware product

• Select the "File -> Import" menu option and select the .ova file downloaded from the Bitnami website. Then click "Continue".
• Once the import is complete, click "Finish" to start the virtual machine.

For a detailed walkthrough, check our VMware tutorial, which uses VMware Fusion as an example. To learn how to use our virtual machines with other VMware products, refer to the VMware Workstation documentation or the VMware vSphere documentation.

What credentials do I need?

You need two sets of credentials:

• The application credentials, consisting of a username and password. These credentials allow you to log in to your new Bitnami application.

• The server credentials, consisting of an SSH username and password. These credentials allow you to log in to your Virtual Machines server using an SSH client and execute commands on the server using the command line.

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?

Password: The administrator password to log in to your application is randomly generated during the first boot. Check the FAQ to learn how to retrieve it.

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

SSH username: bitnami

What is my server IP address?

The IP address is displayed on screen at the end of the boot process, but you can check it at any time by running the following command:

  $ sudo ifconfig

How do I get my SSH key or password?

You can obtain the SSH password from the virtual machine console when it starts up. Click here for more information.

How to access your application?

Once you have imported your Bitnami Virtual Machine, the IP address for your application is displayed on the virtual machine's login screen. Access the application via your browser by entering this IP address.

Check these instructions about how to remotely access the Bitnami application.

What are the default ports?

A port is an endpoint of communication in an operating system that identifies a specific process or a type of service. Bitnami stacks include several services or servers that require a port.

Remember that if you need to open some ports you can follow the instructions given in the FAQ to learn how to open the server ports for remote access.

Port 22 is the default port for SSH connections.

Bitnami opens some ports for the main servers. These are the ports opened by default: 80, 443.

How to start or stop the services?

Each Bitnami stack includes a control script that lets you easily stop, start and restart services. The script is located at /opt/bitnami/ctlscript.sh. Call it without any service name arguments to start all services:

$ sudo /opt/bitnami/ctlscript.sh start

Or use it to restart a single service, such as Apache only, by passing the service name as argument:

$ sudo /opt/bitnami/ctlscript.sh restart apache

Use this script to stop all services:

$ sudo /opt/bitnami/ctlscript.sh stop

Restart the services by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh restart

Obtain a list of available services and operations by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh

How to access the administration panel?

Access the administration panel by browsing to http://SERVER-IP/admin.

How to configure outbound email settings?

• 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.

Troubleshooting Gmail SMTP issues

If you are using Gmail as the outbound email server and you are not able to send email correctly, Google may be blocking sign-in attempts from your apps or devices. Depending on whether or not you use Google Apps, the steps to correct this will differ.

For Google Apps users

If you are a Google Apps user, you will need your administrator to allow users to change the policy for less secure apps. If you are a Google Apps administrator, follow these steps:

• Browse to the Google Apps administration panel.

• Click on "Security" and then "Basic settings".

• Look for the section "Less secure apps" and then click on "Go to settings for less secure apps".

• Select "Allow users to manage their access to less secure apps".

For other Google users

If you do not use Google Apps, follow the steps in the following sections, depending on whether 2-step verification has been enabled on the account or not.

If 2-step verification has not been enabled on the account, follow these steps:

• Browse to the "Less secure apps" page and log in using the account you are having problems with. This option is typically required by many popular email clients, such as Outlook and Thunderbird, and should not be considered unsafe.

• Select the "Turn on" option.

  

If 2-step verification has been enabled on the account, you have to generate an app password. Follow these steps:

• Browse to the "App passwords" page.

• Click "Select app" and choose the app you're using.

• Click "Select device" and choose the device you're using.

• Click the "Generate" button.

• Enter the app password on your device.

• Click the "Done" button.

Here are other options you may try:

• Browse to the web version of Gmail and sign in to your account. Once you're signed in, try to enable access for the application again.

• Browse to the "Unlock Captcha" function page and sign in with your Gmail username and password.

• Disable IMAP from the Gmail web server interface and enable it again.

  

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.

• 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

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 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 find the PostgreSQL database credentials?

• Database username: postgres.
• Database password: The same as the application password. Find out how to obtain application credentials.

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
  

Troubleshooting GitLab CE

Check GitLab troubleshooting documentation for more information about GitLab issues.

How to debug errors in GitLab CE?

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 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
  

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 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

• Generate a new 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 enable HTTPS support with SSL certificates?

Important considerations

• 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:

• Purchase a certificate from a commercial certificate authority.

• Generate a certificate on your own.

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

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
  

Related guides

• Run GitLab in the Cloud