Want to be able to quickly make updates to the handbook or about.gitlab.com 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 about.gitlab.com). We plan on getting you started and then showing you how the end to end flow can work.
Comparison: In-line edit vs WebIDE vs working locally In-line editor, for super-quick minor edits
|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
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.
Not much: Simply 3 things
Git - gets and manages your copy of about.gitlab.com
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: https://git-scm.com/)
Git is powerful and sometimes Git might be intimidating.
(don't panic) because GitLab makes it easy to use Git.
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.
Install Docker and then configure a docker container we call “Middleman” that builds and runs about.gitlab.com locally on your computer.
"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 https://opensource.com/resources/what-docker)
Read and follow step 2 of the about.gitlab.com read.me file for the exact command:
FYI: If you have problems installing Docker, check out the Docker troubleshooting tips at the end of this page.
docker start middleman
docker stop middleman
You should be able to check everything out.
|1. Open a browser and type: |
in the url. If middleman is NOT started, then you will see this response in the browser window.
|2. Go to your terminal window and 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.
|After a few minutes, refresh the browser and you should see the website.|
note: If you have preferred IDE, use it. Atom works for me.
|Step||What it looks like|
|1. In gitlab.com Create a new branch of about.gitlab.com call it “name_of_branch”|
|2. In gitlab.com - create a new MR for the branch I just created|
|3. In the MR - click on Checkout Branch and copy the commands|
|4. Local: Open terminal|
|5. Local: navigate to the Git directory where about.gitlab.com is stored. Command: cd ww* (use the wildcard * so I don’t have to type out ‘www.gitlab.com’|
|6. Local: Start the website running locally: in the terminal type: docker start middleman |
- this tells docker to start the container named 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.
|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
|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.
|10. Local: in Atom - make and save more changes.|
|11. Local: in Browser - review changes|
|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.
|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 the Git server. GitLab will see these changes and kick off a pipeline to build, test and deploy your changes to a review app.
|14. In gitlab.com: When the pipeline finishes, review your changes and then have someone Approve your Merge Request.|
If Docker does not seem to work, here are a few tips:
Look at the status of the container: run the following command in the terminal window:
docker container ls -a
If you need to delete your containers to rebuild them:
docker container prune
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:
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'
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.