Gitlab hero border pattern left svg Gitlab hero border pattern right svg

102 - Working at local speed

Objective: Faster website editing: the basics.

Want to be able to quickly make updates to the handbook or and not have to wait for every commit to go through a pipeline? This workshop will show you how to setup git and docker on your local machine and get your work done 200% faster.

Approach: There may be steps that take too long for everyone to complete LIVE in the workshop (like cloning We plan on getting you started and then showing you how the end to end flow can work.


  1. Install docker
    1. Download and install the Mac version of Docker
    2. You will be asked to create a docker account, then download and install docker
  2. Install an IDE (Install Atom if you don't have an IDE)
    1. Download and install Atom



Comparison: In-line edit vs WebIDE vs working locally In-line editor, for super-quick minor edits

Approach Pros Cons
WebIDE - WebIDE is simple to access
- WebIDE is awesome
- No environment setup
- No git commands necessary
- Easy to make quick edits
- One integrated flow (edit -> MR -> pipeline)
- No advanced git capability
- Full pipeline run to see effect of any changes
- Limited IDE functionality (compared to tools like Atom)
Working locally - Work off-line
- Use whatever editor you want
- Most minimal feedback loop - see effect of changes immediately (just reload your browser)
- Need to remember to push back changes
- Need to know git commands
- Need to get setup (and maintain) local environment
- Need to understand working in a terminal

So why work locally?

Simply, it's faster with the shortest and tightest feedback loops. If you're making a non-trivial change to a page, working locally will often be faster.

What does it take to work locally?

Not much: Simply 3 things

  1. a local copy of (git does this),
  2. an editor or development tool (IDE) - I use Atom,
  3. a way to build and run (docker)

A little terminal time


  1. What is a 'Terminal'? Simply a way to enter commands into your PC. To work with Git and Docker, you need to use the Terminal. Opened Terminal
  2. To open the terminal from
    1. Type 'terminal' in smart search
    2. Or. Go to Launch Pad–> Other, and you should see "Terminal" open terminal
  3. a few key commands to navigate the terminal (from
    • Files
    • ls — lists your files
    • ls -l — lists your files in 'long format', which contains lots of useful information, e.g. the exact size of the file, who owns the file and who has the right to look at it, and when it was last modified.
    • ls -a — lists all files, including the ones whose filenames begin in a dot, which you do not always want to see.
    • ls -la — lists all files in 'long format'
    • more filename — shows the first part of a file, just as much as will fit on one screen. Just hit the space bar to see more or q to quit. You can use /pattern to search for a pattern.


Note: The file from the www-gitlab-com project is a key reference for getting set up to work remotely. Specifically, this section of the are concise directions.

Git - gets and manages your copy of
What is Git ?

"Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. It outclasses SCM tools like Subversion, CVS, Perforce, and ClearCase with features like cheap local branching, convenient staging areas, and multiple workflows." (from:

Git is powerful and sometimes Git might be intimidating.

(don't panic) because GitLab makes it easy to use Git.

Just in case - Bookmark or print the Git CheatSheet and it's probably a good idea to check out GitLab Basics

Step One: Setup your SHA key

First - make sure you have a SHA key set up in GitLab so you can easily synchronize your Git repository with GitLab: Follow the instructions about how to Set up SHA key.


Step Two: Get and Configure Git

  1. Check if Git has already been installed
  2. Install and Configure Git
  3. Clone Use the command in step 1 to clone the website.

Everyone needs a Middleman.


Install Docker and then configure a docker container we call “Middleman” that builds and runs locally on your computer.

What’s docker?

"Docker is a tool designed to make it easier to create, deploy, and run applications by using containers. Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and ship it all out as one package." (from

Step Three: Get Docker and configure Middleman:

  1. Download and install the Mac version of Docker
  2. You will be asked to create a docker account, then download and install docker
  3. Configure Docker to build and run a local copy of

Read and follow step 2 of the file for the exact command:

FYI: If you have problems installing Docker, check out the Docker troubleshooting tips at the end of this page.

  1. a few docker commands you will need:
    To start middleman: docker start middleman
    To see middleman logs: docker logs -f middleman (type control + c to exit the logs program)
    To stop middleman: docker stop middleman

Test it: Does it work locally?


You should be able to check everything out.

1. Open a browser and type: localhost:4567
in the url. If middleman is NOT started, then you will see this response in the browser window.
middleman NOT Started
2. Go to your terminal window and start middleman.
docker start middleman
start middleman
3. Now, refresh your browser to see the web site.
First you will see this response. Notice how it is different from the first message. This tells you it is starting.
Middleman Starting
After a few minutes, refresh the browser and you should see the website. middleman running

Get a development tool to make it easier.

  1. Get an IDE (such as Atom) Download and install Atom

note: If you have preferred IDE, use it. Atom works for me.

Working Remotely. (my workflow)


Step What it looks like
1. In Create a new branch of call it “name_of_branch” new branch new branch
2. In - create a new MR for the branch I just created Create MR MR Title MR Details
3. In the MR - click on Checkout Branch and copy the commands Checkout Branch Copy Git Commands
4. Local: Open terminal open terminal
5. Local: navigate to the Git directory where is stored. Command: cd ww* (use the wildcard * so I don’t have to type out ‘’ Change Director
6. Local: Start the website running locally: in the terminal type: docker start middleman
- this tells docker to start the container named middleman
Start middleman
7. Local: in the terminal Paste the checkout commands and hit enter
- this will refresh your local copy of the project (website) with all the changes
- and will tell git to point to the branch that you’ve created.
Paste terminal Checkout Command (hit enter)
8. Local: Open Atom - the IDE to make edits.
1. Local: in Atom - make a change to a file
2. Local: in Atom - save the change You can either go to the menu file -> save, or use the command+s key combination.
Atom Editing File
9. Local: in Browser- in the URL window - type: http://localhost:4567/
- This will show you what the Middleman container sees in your local files. You will instantly (almost) see the changes after you’ve saved your changes.
middleman running
10. Local: in Atom - make and save more changes. Atom IDE
11. Local: in Browser - review changes middleman running
12. Local: when you’re done. In Atom - On the ‘git tab’.
1. Stage your change
2. Type a commit message that summarizes your change
3. Click Commit to commit your changes to your local branch
- keep working. (making changes, reviewing, committing)… But all of your work is only on your local workstation.
Atom Stage Changes Atom commit changes Atom push changes
13. When you’re ready to push your changes back to the server. Click on Push (command in lower right corner of Atom window)
- When you Push, your commits to your branch will be sent to the Git server. GitLab will see these changes and kick off a pipeline to build, test and deploy your changes to a review app.
Pipeline Running
14. In When the pipeline finishes, review your changes and then have someone Approve your Merge Request.  
15. Local: when you are done working on this branch, delete the local branch. Use 'git branch' command to view all local branches and 'git branch -d your branchname' to delete the local branch Delete Branch


Docker Troubleshooting:

If Docker does not seem to work, here are a few tips:

  1. Look at the status of the container: run the following command in the terminal window: docker container ls -a

  2. If you need to delete your containers to rebuild them: docker container prune

  3. If you need an alternative way to build and run your docker middleman container: Be sure that you’re in the www-gitlab-com directory, and execute:

    1. cd sites/mysite (see monorepo docs for more details)
    2. docker run --rm --name middleman -v "$PWD":/site -w /site -p 4567:4567 -e LC_ALL=C.UTF-8 ruby /bin/bash -c 'bundle install && bundle exec middleman'

With run instead of create you will not need to call additional docker start middleman next. And --rm will ensure, that when exited, the container will be removed so it will not complain next time when you will try to create another one with the same name.

Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license