STM32F4 – Deploy Git MGMT System in under 10 Minutes

UPDATE: Due to Gitlab/Gitlab-CI changes, the script below does not work anymore. I’ll update it in the following months. In the meanwhile, use Gitlab Omnibus package on my Ubuntu 14.04 virtual image with ARM toolchine. The Omnibus package includes both, Gitlab and Gitlab-CI. Be sure to install Gitlab-CI-Runner as well.

Ho, ho, ho! Xmas came early this year, and Santa has a present for all serious embedded software developers (both, good and naughty). Have you ever wanted a private git repository management system that can be accessed via HTTP or SSH? If you answer is positive, then open your present underneath the pine tree, because you will find:

  • A GitLab deploy script.
  • It includes a customized Git Lab CI for ARM-based embedded software development.
    • For a given ARM project repository, this tool automatically runs tests, when a developer pushes some project’s changes to the repository.
    • The test outcome info in turn facilitates code integration, which is very useful in collaborative working environments.
futurama-busting-lamps

The deployment takes approx. 10 minutes to complete (CPU time). Kill some time while waiting by watching the above Futurama episode.

1. Prerequisites

  • Ubuntu 14.04 LTS or similar.
  • Git basics.
  • A copy of my github repository.
    cd ~
    # Install
    sudo apt-get install git 
    
    # Clone my git repository and init submodules
    git clone https://github.com/istarc/stm32.git
    cd ~/stm32
    git submodule update --init
    

2. Deployment Procedure

The GitLab repository management system is deployed by running the following script. The GitLab & GitLab CI systems are deployed as docker containers that require dedicated IP addresses with available HTTP and SSH ports and Internet connectivity.

cd ~/stm32/github
./deploy.sh # The only thing you have to do.

The script stops in the following cases:

  • Misconfigured network interface.
    • Execute the following commands to create the required network interfaces.
      # GitLab's Network Interface
      sudo ifconfig eth0:1 192.168.255.2 \
                    netmask 255.255.255.0 up
      
      # GitLab CI's Network Interface
      sudo ifconfig eth0:2 192.168.255.3 \
                    netmask 255.255.255.0 up
      
    • If dedicated IP addresses are already available, change the default GITLAB_IP, GITLABCI_IP values (see lines 54, 74).
  • Unavailable port. The script stops if HTTP and SSH ports are occupied. In this case you may stop/reconfigure the conflicting services or change the GitLab & GitLab CI HTTP and SSH port values (see lines 61, 67, 82).
    sudo service apache2 stop
    sudo service ssh stop
    
  • Missing software dependencies. In Ubuntu 14.04 LTS the script automatically installs software dependencies, otherwise you have to install them manually.
    sudo apt-get install ruby ruby-mechanize wget curl netcat
    # Add the official docker repository
    # https://docs.docker.com/installation/ubuntulinux/
    sudo apt-get install lxc-docker-1.3.2
    

3. Usage Example

3.1 Create a New Repository

  1. Login to GitLab at http://192.168.255.2 as root with the default password “5iveL!fe”.
  2. Click the plus button on the top right menu to create a new stm32-clone repository imported from my stm32 repository.
    gitlab1
  3. Protect the master branch, so only administrative users have write privileges. Navigate to Settings → Protected branches and protect the master branch.
    gitlab12
  4. Now you may checkout the repository at your host.
    gitlab2

    cd ~
    git clone http://192.168.255.2/root/stm32-clone.git
    cd stm32-clone
    git submodule update --init
    

3.2 Assign a GitLab CI Runner to the Project

  1. Login to GitLab at http://192.168.255.3 as root with the default password “5iveL!fe”.
  2. Add “stm32-clone” repository to the GitLab CI.
    gitlab3
  3. Navigate to settings, change the build script as described below and save changes.
    gitlab4

    git submodule update --init
    make clean
    make
    
  4. Click View on GitLab button. In the new window navigate to Settings → Services → GitLab CI and click on the Test Settings button.
    gitlab5
  5. Check the details of the running test by refocusing to the GitLab CI window and navigating to Builds.
    gitlab6
  6. After the test results are known, the build status information is also displayed in the GitLab.
    gitlab7

3.3 Create a New User

  1. Navigate to gear icon on the top right GitLab menu. Navigate to Users and click the New User icon.
  2. Create the following user.
    gitlab8
  3. You will not receive an e-mail notification, because SMTP account is configured yet. Click on the Edit button to edit the user account to setup John’s password.
    gitlab9
  4. Navigate to Projects → stm32-clone → Manage Access and add John Doe as a new project member with Developer project access permissions.
  5. Clone the stm32-clone repository as John Doe on the host computer.
    mkdir -p ~/tmp/johndoe
    cd ~/tmp/johndoe
    # Clone the repository
    git clone http://192.168.255.2/root/stm32-clone.git
    cd ~/tmp/johndoe/stm32-clone
    git submodule update --init
    # Configure the local user
    git config user.name "john"
    git config user.email "john.doe@dummy.acme"
    

3.4 Continuous Integration

  1. Complete the sections 3.1 – 3.3.
  2. Now suppose John Doe wants to add a new feature in the stm32-clone repository, e.g. a new FreeRTOS project.
    1. For this purpose he creates a new branch called featureX.
      cd ~/tmp/johndoe/stm32-clone
      git checkout -b featureX
      
    2. Then he creates a new FreeRTOS project using my project wizard.
      cd ~/tmp/johndoe/stm32-clone
      mkdir -p examples/featureX
      cd examples/featureX
      ../../mbed-project-wizard/gen-stm32f407-GCC-project.sh \
                                                  mbed-freertos
      
    3. He commits the local changes and pushes the branch to the GitLab.
      cd ~/tmp/johndoe/stm32-clone/examples/featureX
      git add .
      git commit -m "Added a new FreeRTOS project"
      git push origin featureX
      # Username for 'http://192.168.255.2': john
      # Password for 'http://john@192.168.255.2':
      # Counting objects: 34, done.
      # Delta compression using up to 8 threads.
      # Compressing objects: 100% (20/20), done.
      # Writing objects: 100% (21/21), 75.94 KiB
      # Total 21 (delta 2), reused 1 (delta 0)
      # To http://192.168.255.2/root/stm32-clone.git
      # * [new branch] featureX -> featureX
      
  3. This change is visible in the GitLab. Login to the GitLab with John Doe and request a merge request with the master branch.
    gitlab11

    1. Observe that GitLab CI immediately tests the featureX branch.
      Denzel-BreakTheBuild
    2. Even though this branch passes the tests, it cannot be merged with the master branch by John Doe due to insufficient privileges.
      gitlab13
  4. Login to GitLab as root. Click on the John Doe’s merge request in the Activity window.
    gitlab14

    1. You can now authorize the merge request. But beware! With great power comes great responsibility. The decision making is a lot easier with test outcome information provided by the GitLab CI. 😎

      This slideshow requires JavaScript.

4. Data Persistence

The deployed docker containers store GitLab and GitLab CI data on the host computer in the “/opt” directory. This means your data is saved, when the containers are stopped or even deleted.

You may use the deploy script to start the existing containers or to initialize new containers over the existing data. You may test this by running the following commands.

cd ~/stm32/github

# WARNING! Stops ALL docker containers!
sudo docker stop $(sudo docker ps -a -q)

# WARNING! Deletes ALL docker containers!
# sudo docker rm $(sudo docker ps -a -q)

# 1. Start the existing containers over existing data.
# 2. Uncomment docker rm command to intialize
#    new containers over existing data.
./deploy.sh

5. References

I use Sameer Naik’s GitLab and GitLab CI docker images. I adapted his GitLab CI Runner image to be suitable for ARM-based embedded software development.

Advertisements

About istarc

Embedded Systems Developer.
This entry was posted in Embedded Systems, STM32F4 and tagged , , , , , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s