diff options
| author | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-09-30 12:58:41 +0000 |
|---|---|---|
| committer | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-09-30 12:58:41 +0000 |
| commit | 91a91557ce4aeeafa34856009359bb6c34e3e10e (patch) | |
| tree | b8b712de74856645d9c4a97faff47dbd7f6cde08 /doc | |
| parent | 5838d1ba892872553dcd4e3945a3fab8faf339a4 (diff) | |
| parent | b9daced7a2814fa74a3f0dddf38858100678c6b1 (diff) | |
| download | gitlab-ce-91a91557ce4aeeafa34856009359bb6c34e3e10e.tar.gz | |
Merge branch 'master' into 'fix_oauth_doc'
# Conflicts:
# doc/api/oauth2.md
Diffstat (limited to 'doc')
28 files changed, 1700 insertions, 6 deletions
diff --git a/doc/README.md b/doc/README.md index dd0eb97489e..4ff1a0582c8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -19,6 +19,7 @@ - [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects. - [Webhooks](web_hooks/web_hooks.md) Let GitLab notify you when new code has been pushed to your project. - [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN. +- [University](university/README.md) Learn Git and GitLab through videos and courses. ## Administrator documentation diff --git a/doc/api/builds.md b/doc/api/builds.md index dce666445d0..e8a9e4743d3 100644 --- a/doc/api/builds.md +++ b/doc/api/builds.md @@ -40,6 +40,12 @@ Example of response "finished_at": "2015-12-24T17:54:27.895Z", "id": 7, "name": "teaspoon", + "pipeline": { + "id": 6, + "ref": "master", + "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "status": "pending" + } "ref": "master", "runner": null, "stage": "test", @@ -78,6 +84,12 @@ Example of response "finished_at": "2015-12-24T17:54:24.921Z", "id": 6, "name": "spinach:other", + "pipeline": { + "id": 6, + "ref": "master", + "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "status": "pending" + } "ref": "master", "runner": null, "stage": "test", @@ -146,6 +158,12 @@ Example of response "finished_at": "2016-01-11T10:14:09.526Z", "id": 69, "name": "rubocop", + "pipeline": { + "id": 6, + "ref": "master", + "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "status": "pending" + } "ref": "master", "runner": null, "stage": "test", @@ -170,6 +188,12 @@ Example of response "finished_at": "2015-12-24T17:54:33.913Z", "id": 9, "name": "brakeman", + "pipeline": { + "id": 6, + "ref": "master", + "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "status": "pending" + } "ref": "master", "runner": null, "stage": "test", @@ -231,6 +255,12 @@ Example of response "finished_at": "2015-12-24T17:54:31.198Z", "id": 8, "name": "rubocop", + "pipeline": { + "id": 6, + "ref": "master", + "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "status": "pending" + } "ref": "master", "runner": null, "stage": "test", diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 3ea481eadb5..5ef5e3f5744 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -48,7 +48,7 @@ You should then use the `code` to request an access token. >**Important:** It is highly recommended that you send a `state` value with the request to `/oauth/authorize` and validate that value is returned and matches in the redirect request. -This is important to prevent [CSFR attacks](http://www.oauthsecurity.com/#user-content-authorization-code-flow), +This is important to prevent [CSRF attacks](http://www.oauthsecurity.com/#user-content-authorization-code-flow), `state` really should have been a requirement in the standard! ### 3. Requesting the access token @@ -134,4 +134,4 @@ access_token = client.password.get_token('user@example.com', 'secret') puts access_token.token ``` -[personal access tokens]: ./README.md#personal-access-tokens +[personal access tokens]: ./README.md#personal-access-tokens
\ No newline at end of file diff --git a/doc/api/projects.md b/doc/api/projects.md index 750ce1508df..869907b0dd7 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -899,6 +899,7 @@ Parameters: - `id` (required) - The ID or NAMESPACE/PROJECT_NAME of the project to be forked - `group_id` (required) - The ID of a group - `group_access` (required) - Level of permissions for sharing +- `expires_at` - Share expiration date in ISO 8601 format: 2016-09-26 ## Hooks diff --git a/doc/api/settings.md b/doc/api/settings.md index aaa2c99642b..f7ad3b4cc8e 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -41,7 +41,9 @@ Example response: "gravatar_enabled" : true, "sign_in_text" : null, "container_registry_token_expire_delay": 5, - "repository_storage": "default" + "repository_storage": "default", + "koding_enabled": false, + "koding_url": null } ``` @@ -72,7 +74,9 @@ PUT /application/settings | `after_sign_out_path` | string | no | Where to redirect users after logout | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes | | `repository_storage` | string | no | Storage path for new projects. The value should be the name of one of the repository storage paths defined in your gitlab.yml | -| `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. +| `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | +| `koding_enabled` | boolean | no | Enable Koding integration. Default is `false`. | +| `koding_url` | string | yes (if `koding_enabled` is `true`) | The Koding instance URL for integration. | ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings?signup_enabled=false&default_project_visibility=1 @@ -103,6 +107,8 @@ Example response: "user_oauth_applications": true, "after_sign_out_path": "", "container_registry_token_expire_delay": 5, - "repository_storage": "default" + "repository_storage": "default", + "koding_enabled": false, + "koding_url": null } ``` diff --git a/doc/install/installation.md b/doc/install/installation.md index 3ac813aa914..cb4c1f4a091 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -381,7 +381,7 @@ sudo usermod -aG redis git GitLab Shell is an SSH access and repository management software developed specially for GitLab. # Run the installation task for gitlab-shell (replace `REDIS_URL` if needed): - sudo -u git -H bundle exec rake gitlab:shell:install REDIS_URL=unix:/var/run/redis/redis.sock RAILS_ENV=production + sudo -u git -H bundle exec rake gitlab:shell:install REDIS_URL=unix:/var/run/redis/redis.sock RAILS_ENV=production SKIP_STORAGE_VALIDATION=true # By default, the gitlab-shell config is generated from your main GitLab config. # You can review (and modify) the gitlab-shell config as follows: diff --git a/doc/university/README.md b/doc/university/README.md new file mode 100644 index 00000000000..6ca1c20c9b2 --- /dev/null +++ b/doc/university/README.md @@ -0,0 +1,139 @@ + +## What is GitLab University + +_GitLab University_ has as a goal to teach the fundamentals of **Version Control with Git and GitLab** through courses that cover topics which can be mastered in around 2 hours. + +_University materials don't replace our [Documentation](http://docs.gitlab.com) or [Blog Articles](https://about.gitlab.com/blog/)._ + +--- + +### On this page + ++ [GITx] Git ++ [OPSx] DevOps ++ [GLBx] GitLab Basics ++ [INTx] GitLab Integrations ++ [GLFx] GitLab Workflows ++ [GLEx] GitLab Enterprise Edition extra features ++ [GCIx] GitLab CI ++ [ECO] Ecosystem ++ [COM] Competition comparison ++ [SPTx] Support Bootcamp ++ [SLSx] Sales Bootcamp ++ [TRAx] Trainings + +--- + ++ [GIT1] [Version Control Systems](https://docs.google.com/presentation/d/16sX7hUrCZyOFbpvnrAFrg6tVO5_yT98IgdAqOmXwBho/edit#slide=id.g72f2e4906_2_29) ++ [GIT2] [Operating Systems and How Git Works](https://drive.google.com/a/gitlab.com/file/d/0B41DBToSSIG_OVYxVFJDOGI3Vzg/view?usp=sharing) ++ [GIT3] [Intro to Git](https://www.codeschool.com/account/courses/try-git) + +--- + ++ [OPS1] [What is Omnibus](https://www.youtube.com/watch?v=XTmpKudd-Oo) ++ [OPS2] [Installing GitLab](https://www.youtube.com/watch?v=Q69YaOjqNhg) ++ [OPS3] [Configuring an external PostgreSQL database](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#using-a-non-packaged-postgresql-database-management-server) ++ [OPS5] [Importing from Other Tools or SVN](http://doc.gitlab.com/ee/workflow/importing/) ++ [OPS6] [High Availability Documentation](https://about.gitlab.com/high-availability/) ++ [OPS7] [Managing LDAP, Active Directory](https://www.youtube.com/watch?v=HPMjM-14qa8) ++ [OPS8] [Scalability and High Availability](https://www.youtube.com/watch?v=cXRMJJb6sp4&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e&index=2) ++ [OPS9] [High Availability on AWS](high-availability/aws/README.md) + +--- + ++ [GLB1] [Terminology](glossary/README.md) ++ [GLB2] [GitLab Basics](http://doc.gitlab.com/ce/gitlab-basics/README.html) ++ [GLB3] [Demo of GitLab.com](https://www.youtube.com/watch?v=WaiL5DGEMR4) ++ [GLB4] [Create and Add your SSH key to GitLab](https://www.youtube.com/watch?v=54mxyLo3Mqk) ++ [GLB5] [Repositories, Projects and Groups](https://www.youtube.com/watch?v=4TWfh1aKHHw&index=1&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) ++ [GLB6] [Creating a Project in GitLab](https://www.youtube.com/watch?v=7p0hrpNaJ14) ++ [GLB7] [Issues and Merge Requests](https://www.youtube.com/watch?v=raXvuwet78M) ++ [GLB8] [Big files in Git (Git LFS, Annex)](https://gitlab.com/gitlab-org/University/blob/master/classes/git_lfs_and_annex.md) + +--- + ++ [INT1] [JIRA and Jenkins integrations in GitLab](https://gitlabmeetings.webex.com/gitlabmeetings/ldr.php?RCID=44b548147a67ab4d8a62274047146415) ++ [INT2] [Integrating JIRA with GitLab](http://doc.gitlab.com/ee/integration/jira.html) ++ [INT3] [Integrating Jenkins with GitLab](http://doc.gitlab.com/ee/integration/jenkins.html) ++ [INT4] [Integrating Bamboo with GitLab](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/project_services/bamboo.md) ++ [INT5] [Documentation on Integrating Slack with GitLab](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/integration/slack.md) + +--- + ++ [GLF1] [GitLab Flow](https://www.youtube.com/watch?v=UGotqAUACZA) + +--- + ++ [GLE1] [Configuring an external MySQL database](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#using-a-mysql-database-management-server-enterprise-edition-only) ++ [GLE2] [Managing Permissions within EE](https://www.youtube.com/watch?v=DjUoIrkiNuM) ++ [GLE3] [Upcoming in EE and Big files in Git (Git LFS, Annex)](https://gitlab.com/gitlab-org/University/blob/master/classes/upcoming_in_ee.md) + +--- + ++ [GCI1] [GitLab CI product page](https://about.gitlab.com/gitlab-ci/) ++ [GCI2] [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) + +--- + ++ [COM1] [GitLab compared to other tools](https://about.gitlab.com/comparison/) ++ [COM2] [Compare GitLab versions](https://about.gitlab.com/features/#compare) ++ [COM3] [Innersourcing article](https://about.gitlab.com/2014/09/05/innersourcing-using-the-open-source-workflow-to-improve-collaboration-within-an-organization/) + +--- + ++ [ECO1] [Ecosystem Overview](https://www.youtube.com/watch?v=sXlhgPK1NTY&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e&index=6) ++ [ECO2] [Positioning FAQ](https://about.gitlab.com/handbook/positioning-faq) ++ [ECO3] [GitLab Ecosystem slides](https://docs.google.com/presentation/d/1vCU-NbZWz8NTNK8Vu3y4zGMAHb5DpC8PE5mHtw1PWfI/edit) ++ [ECO4] [Customer Use-Cases](https://about.gitlab.com/handbook/use-cases/) + +--- + ++ [SPT1] [Support Path](support/README.md) ++ [SPT2] [End User Training Material](https://gitlab.com/gitlab-org/University/blob/master/training/user_training.md) ++ [SPT3] [Materials for Training Sessions](https://gitlab.com/gitlab-org/University/tree/master/training/topics) + +--- + ++ [SLS1] [Sales Path (redirect to sales handbook)](https://about.gitlab.com/handbook/sales-onboarding/) ++ [SLS2] [GitLab Direction](https://about.gitlab.com/direction/) + +--- + ++ [TRA1] [End User Training](training/end-user/README.md) + +--- + +### External Resources + ++ [DOC] GitLab Documentation + + [Set up and use GitLab Pages](http://doc.gitlab.com/ee/pages/README.html) + + [Markdown Reference](http://doc.gitlab.com/ce/markdown/markdown.html) + ++ [GLW] GitLab Workshop (@ Platzi) + + [GitLab Workshop Part 1: Basics of Git and GitLab](https://courses.platzi.com/classes/git-gitlab/) + + [Create a GitLab Account](https://courses.platzi.com/classes/git-gitlab/concepto/first-steps/create-an-account-on-gitlab/material/) + ++ [GLY] GitLab YouTube Videos + + [Making GitLab Great for Everyone, our response to the Dear GitHub letter](https://www.youtube.com/watch?v=GGC40y4vMx0) + + [Compared to Atlassian (Recorded on 2016-03-03) ](https://youtu.be/Nbzp1t45ERo) + ++ [GLI] GitLab Team-Only Access + + [GitLab architecture for noobs](https://dev.gitlab.org/gitlab/gitlabhq/blob/master/doc/development/architecture.md) + + [Client Assessment of GitLab versus GitHub](https://docs.google.com/a/gitlab.com/spreadsheets/d/18cRF9Y5I6I7Z_ab6qhBEW55YpEMyU4PitZYjomVHM-M/edit?usp=sharing) + ++ [KNT] Slides & Keynotes by GitLabbers & other individuals + + [Why Git and GitLab slide deck](https://docs.google.com/a/gitlab.com/presentation/d/1RcZhFmn5VPvoFu6UMxhMOy7lAsToeBZRjLRn0LIdaNc/) + + [Git Workshop](https://docs.google.com/presentation/d/1JzTYD8ij9slejV2-TO-NzjCvlvj6mVn9BORePXNJoMI/) + ++ Others (not created by GitLab) + + [Dev Ops terminology](https://xebialabs.com/glossary/) + + [Continuous Delivery vs Continuous Deployment](https://www.youtube.com/watch?v=igwFj8PPSnw) + + [Periodic Table of DevOps Tools](https://xebialabs.com/periodic-table-of-devops-tools/) + + [State of Dev Ops 2015 Report by Puppet Labs](https://puppetlabs.com/sites/default/files/2015-state-of-devops-report.pdf) Insightful Chapters to understand the Impact of Continuous Delivery on Performance (Chapter 4), the Application Architecture (Chapter 5) and How IT Managers can help their teams win (Chapter 6). + + [2011 WSJ article by Mark Andreeson - Software is Eating the World](http://www.wsj.com/articles/SB10001424053111903480904576512250915629460) + + [2014 Blog post by Chris Dixon - Software eats software development](http://cdixon.org/2014/04/13/software-eats-software-development/) + + [2015 Venture Beat article - Actually, Open Source is Eating the World](http://venturebeat.com/2015/12/06/its-actually-open-source-software-thats-eating-the-world/) + + [Customer review of GitLab with talking points on why they prefer GitLab](https://www.enovate.co.uk/web-design-blog/2015/11/25/gitlab-review/) + + [3rd party tool comparison](http://technologyconversations.com/2015/10/16/github-vs-gitlabs-vs-bitbucket-server-formerly-stash/) + + [Amazon's transition to Continuous Delivery](https://www.youtube.com/watch?v=esEFaY0FDKc) + + [Article on Continuous Integration from ThoughtWorks](https://www.thoughtworks.com/continuous-integration) diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md new file mode 100644 index 00000000000..a86ff165f2e --- /dev/null +++ b/doc/university/glossary/README.md @@ -0,0 +1,482 @@ + +## What is the Glossary + +This contains a simplified list and definitions of some of the terms that you will encounter in your day to day activities when working with GitLab. +Please add any terms that you discover that you think would be useful for others. + +### 2FA + +User authentication by combination of 2 different steps during login. This allows for more security. + +### Access Levels + +Process of selective restriction to create, view, modify or delete a resource based on a set of assigned permissions. +See, [GitLab's Permission Guidelines](http://doc.gitlab.com/ce/permissions/permissions.html) + +### Active Directory (AD) + +A Microsoft based directory service for windows domain networks. It uses LDAP technology under the hood + +### Agile + +Building and delivering software in phases/parts rather than trying to build everything at once then delivering to the user/client. The later is known as a WaterFall model + +### Application Lifecycle Management (ALM) + +Entire product lifecycle management process for an application. From requirements management, development and testing until deployment. + +### Artifactory + +Version control for binaries. + +### Artifacts + +objects (usually binary and large) created by a build process + +### Atlassian + +A company that develops software products for developers and project managers including Bitbucket, Jira, Hipchat, Confluence, Bamboo. See [Atlassian] (https://www.atlassian.com) + +### Audit Log + +*** Needs definition here + +### Auto Defined User Group + +User groups are a way of centralizing control over important management tasks, particularly access control and password policies. +A simple example of such groups are the users and the admins groups. +In most of the cases these groups are auto defined in terms of access, rules of usage, conditions to be part of, etc... + +### Bamboo + +Atlassian's CI tool similar to GitLab CI and Jenkins + +### Basic Subscription + +Entry level subscription for GitLab EE currently available in packs of 10 see [Basic subscription](https://about.gitlab.com/pricing/) + +### Bitbucket + +Atlassian's web hosting service for Git and Mercurial Projects i.e. GitLab.com competitor + +### Branch + +A branch is a parallel version of a repository. Allows you to work on the repository without you affecting the "master" branch. Allows you to make changes without affecting the current "live" version. When you have made all your changes to your branch you can then merge to the master and to make the changes fo "live". + +### Branded Login + +Having your own logo on your GitLab instance login page instead of the GitLab logo. + +### CEPH + +is a distributed object store and file system designed to provide excellent performance, reliability and scalability. + +### Clone + +A copy of a repository stored on your machine that allows you to use your own editor without being online, but still tracks the changes made remotely. + +### Code Review + +Examination of a progam's code. The main aim is to maintain high standards quality of code that is being shipped. + +### Code Snippet + +A small amount of code. Usually for the purpose of showing other developers how +to do something specific or reproduce a problem. + +### Collaborator + +Person with read and write access to a repository who has been invited by repository owner. + +### Commit + +Is a change (revision) to a file, and also creates an ID that allows you to see revision history and who made the changes. + +### Community + +Everyone who is using GitLab + +### Confluence + +Atlassian's product for collaboration of documents and projects. + +### Continuous Deivery + +Continuous delivery is a series of practices designed to ensure that code can be rapidly and safely deployed to production by delivering every change to a production-like environment and ensuring business applications and services function as expected through rigorous automated testing. + +### Continuous Deployment + +Continuous deployment is the next step of continuous delivery: Every change that passes the automated tests is deployed to production automatically. + +### Continuous Integration + +A process that involves adding new code commits to source code with the combined code being run on an automated test to ensure that the changes do not break the software. + +### Contributor + +Term used to a person contributing to an Open Source Project. + +### Data Centre + +Atlassian product for High Availability. + +### Deploy Keys + +An SSH key stored on the your server that grants access to a single GitLab repository. This is used by a GitLab runner to clone a project's code so that tests can be run against the checked out code. + +### Developer + +For us (GitLab) this means a software developer, i.e. someone who makes software. It is also one of the levels of access in our multi level approval system. + +### Diff + +Is the difference between two commits, or saved changes. This will also be shown visually after the changes. + +### Docker + +Containers wrap up a piece of software in a complete filesystem that contains everything it needs to run: code, runtime, system tools, system libraries – anything you can install on a server. +This guarantees that it will always run the same, regardless of the environment it is running in. + +### Fork + +Your own copy of a repository that allows you to make changes to the repository without affecting the original. + +### Gerrit + +A code review tool built on top of Git. + +### Git Hooks + +Are scripts you can use to trigger actions at certain points. + +### GitHost.io + +Is a single-tenant solution that provides GitLab CE or EE as a managed service. GitLab Inc. is responsible for +installing, updating, hosting, and backing up customers own private and secure GitLab instance. + +### GitHub + +A web-based Git repository hosting service with an enterprise offering. Its main features are: issue tracking, pull request with code review, abundancy of integrations and wiki. As of April 2016, the service has over 14 million users. It offers free public repos, private repos and enterprise services are paid. + +### GitLab CE + +Our free on Premise solution with >100,000 users + +### GitLab CI + +Our own Continuos Integration feature that is shipped with each instance + +### GitLab EE + +Our premium on premise solution that currently has Basic, Standard and Plus subscription packages with additional features and support. + +### GitLab.com + +Our free SaaS for public and private repositories. + +### Gitolite + +Is basically an access layer that sits on top of Git. Users are granted access to repos via a simple config file and you as an admin only needs the users public SSH key and a username from the user. + +### Gitorious + +A web based hosting service for projects using Git. It was acquired by GitLab and we discontinued the service. [Gitorious Acquisition Blog Post](https://about.gitlab.com/2015/03/03/gitlab-acquires-gitorious/) + +### HADR + +Sometimes written HA/DR. High Availability for Disaster Recovery. Usually refers to a strategy having a failover server in place in case the main server fails. + +### Hip Chat + +Atlassian's real time chat application for teams. Competitor to Slack, RocketChat and MatterMost. + +### High Availability + +Refers to a system or component that is continuously operational for a desirably long length of time. Availability can be measured relative to "100% operational" or "never failing." + +### Issue Tracker + +A tool used to manage, organize, and maintain a list of issues, making it easier for an organization to manage. + +### Jenkins + +An Open Source CI tool written using the Java programming language. Does the same job as GitLab CI, Bamboo, Travis CI. It is extremely popular. see [Jenkins](https://jenkins-ci.org/) + +### Jira + +Atlassian's project management software. i.e. a complex issue tracker. See[Jira](https://www.atlassian.com/software/jira) + +### Kerberos + +A network authentication protocol that uses secret-key cryptography for security. + +### Kubernetes + +An open source container cluster manager originally designed by Google. It's basically a platform for automating deployment, scaling, and operations of application containers over clusters of hosts. + +### Labels + +An identifier to describe a group of one or more specific file revisions + +### LDAP + +Lightweight Directory Access Protocol - basically its a directory (electronic address book) with user information e.g. name, phone_number etc + +### LDAP User Authentication + +Allowing GitLab to sign in people from an LDAP server i.e. Allow people whose names are on the electronic user directory server) to be able to use their LDAP accounts to login. + +### LDAP Group Sync + +Allows you to synchronize the members of a GitLab group with one or more LDAP groups. + +### Git LFS + +Git Large File Storage. A way to enable git to handle large binary files by using reference pointers within small text files to point to the large files. + +### Linux + +An operating system like Windows or OS X. It is mostly used by software developers and on servers. + +### Markdown + +Is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool by the same name. +Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. + +### Maria DB + +A community developed fork/variation of MySQL. MySQL is owned by Oracle. + +### Master + +Name of the default branch in every git repository. + +### Mercurial + +A free distributed version control system like Git. Think of it as a competitor to Git. + +### Merge + +Takes changes from one branch, and applies them into another branch. + +### Meteor + +A hip platform for building javascript apps.[Meteor] (https://www.meteor.com) + +### Milestones + +Allows you to track the progress on issues, and merge requests, which allows you to get a snapshot of the progress made. + +### Mirror Repositories + +You can set up a project to automatically have its branches, tags, and commits updated from an upstream repository. This is useful when a repository you're interested in is located on a different server, and you want to be able to browse its content and its activity using the familiar GitLab interface. + +### MIT License + +A type of software license. It lets people do anything with your code with proper attribution and without warranty. It is the most common license for open source applications written in Ruby on Rails. GitLab CE is issued under this license. +This means, you can download the code, modify it as you want even build a new commercial product using the underlying code and its not illegal. The only condition is that there is no form of waranty provided by GitLab so whatever happens if you use the code is your own problem. + +### Mondo + +*** Needs definition here + +### Multi LDAP Server + +*** Needs definition here + +### My SQL + +A relational database. Currently only supported if you are using EE. It is owned by Oracle. + +### Namespace + +In computing, a namespace is a set of symbols that are used to organize objects of various kinds, so that these objects may be referred to by name. + +Prominent examples include: +- file systems are namespaces that assign names to files; +- programming languages organize their variables and subroutines in namespaces; +- computer networks and distributed systems assign names to resources, such as computers, printers, websites, (remote) files, etc. + +### Nginx + +(pronounced "engine x") is a web server. It can act as a reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and an HTTP cache. + +### oAuth + +Is an open standard for authorization, commonly used as a way for Internet users to log into third party websites using their Microsoft, Google, Facebook or Twitter accounts without exposing their password. + +### Omnibus Packages + +Omnibus is a way to package the different services and tools required to run GitLab, so that users can install it without as much work. + +### On Premise + +On your own server. In GitLab, this refers to the ability to download GitLab EE/GitLab CE and host it on your own server rather than using GitLab.com which is hosted by GitLab Inc's servers. + +### Open Source Software + +Software for which the original source code is freely available and may be redistributed and modified. + +### Owner + +This is the most powerful person on a GitLab project. He has the permissions of all the other users plus the additional permission of being able to destroy i.e. delete the project + +### PaaS + +Typically referred to in regards to application development, it is a model in which a cloud provider delivers hardware and software tools to its users as a service + +### Perforce + +The company that produces Helix. A commercial, proprietary, centralised VCS well known for it's ability to version files of any size and type. They OEM a re-branded version of GitLab called "GitSwarm" that is tightly integrated with their "GitFusion" product, which in turn represents a portion of a Helix repository (called a depot) as a git repo + +### Phabricator + +Is a suite of web-based software development collaboration tools, including the Differential code review tool, the Diffusion repository browser, the Herald change monitoring tool, the Maniphest bug tracker and the Phriction wiki. Phabricator integrates with Git, Mercurial, and Subversion. + +### Piwik Analytics + +An open source analytics software to help you analyze web traffic. It is similar to google analytics only that google analytics is not open source and information is stored by google while in Piwik the information is stored in your own server hence fully private. + +### Plus Subscription + +GitLab Premium EE subscription that includes training and dedicated Account Management and Service Engineer and complete support package [Plus subscription](https://about.gitlab.com/pricing/) + +### PostgreSQL + +A relational database. Touted as the most advanced open source database. + +### Protected Branches + +A feature that protects branches from unauthorized pushes, force pushing or deletion. + +### Pull + +Git command to synchronize the local repository with the remote repository, by fetching all remote changes and merging them into the local repository. + +### Puppet + +A popular devops automation tool + +### Push + +Git command to send commits from the local repository to the remote repository. + +### RE Read Only + +Permissions to see a file and it's contents, but not change it + +### Rebase + +Moves a branch from one commit to another. This allows you to re-write your project's history. + +### Git Repository + +Storage location of all files which are tracked by git. + +### Requirements management + +*** Needs definition here + +### Revision + +*** Needs definition here + +### Revision Control + +Also known as version control or source control, is the management of changes to documents, computer programs, large web sites, and other collections of information. Changes are usually identified by a number or letter code, termed the "revision number", "revision level", or simply "revision". + +### RocketChat + +An open source chat application for teams. Very similar to Slack only that is is open-source. + +### Runners + +Actual build machines/containers that run/execute tests you have specified to be run on GitLab CI + +### SaaS + +Software as a service. Software is hosted centrally and accessed on-demand i.e. when you want to. This refers to GitLab.com in our scenario + +### SCM + +Software Configuration Management. Often used by people when they mean Version Control + +## Scrum + +An Agile framework designed to help complete complex (typically) software projects. It's made up of several parts: product requirments backlog, sprint plannnig, sprint (development), sprint review, retrospec (analyzing the sprint). The goal is to end up with potentially shippable products. + +### Scrum Board + +The board used to track the status and progress of each of the sprint backlog items. + +### Slack + +Real time messaging app for teams. Used internally by GitLab + +### Slave Servers + +Also known as secondary servers. They help to spread the load over multiple machines, they also provide backups when the master/primary server crashes. + +### Source Code + +Program code as typed by a computer programmer. i.e. it has not yet been compiled/translated by the computer to machine language. + +### SSH Key + +A unique identifier of a computer. It is used to identify computers without the need for a password. e.g. On GitLab I have added the ssh key of all my work machines so that the GitLab instance knows that it can accept code pushes and pulls from this trusted machines whose keys are I have added. + +### SSO + +Single Sign On. An authentication process that allows you enter one username and password to access multiple applications. + +### Standard Subscription + +Our mid range EE subscription that includes 24/7 support, support for High Availability [Standard Subscription](https://about.gitlab.com/pricing/) + +### Stash + +Atlassian's Git On-Premises solution. Think of it as Atlassian's GitLab EE. It is now known as BitBucket Server. + +### Subversion + +Non-proprietary, centralized version control system. + +### Sudo + +A program that allows you to perform superuser/administrator actions on Unix Operating Systems e.g. Linux, OS X. It actually stands for 'superuser do' + +### SVN + +Abbreviation for Subversion. + +### Tag + +Represents a version of a particular branch at a moment in time. + +### Tool Stack + +Set of tools used in a process to achieve a common outcome. E.g. set of tools used in Application Lifecycle Management. + +### Trac + +An Open Source project management and bug tracking web application. + +### User + +Anyone interacting with the software. + +### VCS + +Version Control Software + +### Waterfall + +A model of building software that involves collecting all requirements from the customer, then building and refining all the requirements and finally delivering the COMPLETE software to the customer that meets all the requirements specified by the customer + +### Webhooks + +A way for for an app to provide other applications with real-time information. e.g. send a message to a slack channel when a commit is pushed + +### Wiki + +A website/system that allows for collaborative editing of its content by the users. In programming, they usually contain documentation of how to use the software diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md new file mode 100644 index 00000000000..088f1cd7290 --- /dev/null +++ b/doc/university/high-availability/aws/README.md @@ -0,0 +1,387 @@ + +# High Availability on AWS + +GitLab on AWS can leverage many of the services that are already +configurable with High Availability. These services have a lot of +flexibility and are able to adopt to most companies, best of all is the +ability to automate both vertical and horizontal scaling. + +In this article we'll go through a basic HA setup where we'll start by +configuring our Virtual Private Cloud and subnets to later integrate +services such as RDS for our database server and ElastiCache as a Redis +cluster to finally manage them within an auto scaling group with custom +scaling policies. + +*** + +## Where to Start + +Login to your AWS account through the `My Account` dropdown on +`https://aws.amazon.com` or through the URI assigned to your team such as +`https://myteam.signin.aws.amazon.com/console/`. You'll start on the +Amazon Web Services console from where we can choose all of the services +we'll be using to configure our cloud infrastructure. + +*** + +## Network + +We'll start by creating a VPC for our GitLab cloud infrastructure, then +we can create subnets to have public and private instances in at least +two AZs. Public subnets will require a Route Table keep an associated +Internet Gateway. + +### VPC + +Start by looking for the VPC option on the web console. Now create a new +VPC. We can use `10.0.0.0/16` for the CIDR block and leave tenancy as +default if we don't require dedicated hardware. + + + +If you're setting up the Elastic File System service then select the VPC +and from the Actions dropdown choose Edit DNS Hostnames and select Yes. + +### Subnet + +Now let's create some subnets in different Availability Zones. Make sure +that each subnet is associated the the VPC we just created, that it has +a distinct VPC and lastly that CIDR blocks don't overlap. This will also +allow us to enable multi AZ for redundancy. + +We will create private and public subnets to match load balancers and +RDS instances as well. + + + +The subnets are listed with their name, AZ and CIDR block: + +* gitlab-public-10.0.0.0 - us-west-2a - 10.0.0.0 +* gitlab-private-10.0.1.0 - us-west-2a - 10.0.1.0 +* gitlab-public-10.0.2.0 - us-west-2b - 10.0.2.0 +* gitlab-private-10.0.3.0 - us-west-2b - 10.0.3.0 + +### Route Table + +Up to now all our subnets are private. We need to create a Route Table +to associate an Internet Gateway. On the same VPC dashboard choose +Route Tables on the left column and give it a name and associate it to +our newly created VPC. + + + + +### Internet Gateway + +Now still on the same dashboard head over to Internet Gateways and +create a new one. After its created pres on the `Attach to VPC` button and +select our VPC. + + + +### Configure Subnets + +Go back to the Router Tables screen and select the newly created one, +press the Routes tab on the bottom section and edit it. We need to add a +new target which will be our Internet Gateway and have it receive +traffic from any destination. + + + +Before leaving this screen select the next tab to the rgiht which is +Subnet Associations and add our public subnets. If you followed our +naming convention they should be easy to find. + +*** + +## Database with RDS + +For our database server we will use Amazon RDS which offers Multi AZ +for redundancy. Lets start by creating a subnet group and then we'll +create the actual RDS instance. + +### Subnet Group + +From the RDS dashboard select Subnet Groups. Lets select our VPC from +the VPC ID dropdown and at the bottom we can add our private subnets. + + + +### RDS + +Select the RDS service from the Database section and create a new +PostgreSQL instance. After choosing between a Production or +Development instance we'll start with the actual configuration. On the +image bellow we have the settings for this article but note the +following two options which are of particular interest for HA: + +1. Multi-AZ-Deployment is recommended as redundancy. Read more at +[High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html) +1. While we chose a General Purpose (SSD) for this article a Provisioned +IOPS (SSD) is best suited for HA. Read more about it at +[Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html) + + + +The rest of the setting on this page request a DB identifier, username +and a master password. We've chosen to use `gitlab-ha`, `gitlab` and a +very secure password respectively. Keep these in hand for later. + + + +Make sure to choose our gitlab VPC, our subnet group, not have it public, +and to leave it to create a new security group. The only additional +change which will be helpful is the database name for which we can use +`gitlabhq_production`. + +*** + +## ElastiCache + +EC is an in-memory hosted caching solution. Redis maintains its own +persistance and is used for certain types of application. + +Let's choose the ElastiCache service in the Database section from our +AWS console. Now lets create a cache subnet group which will be very +similar to the RDS subnet group. Make sure to select our VPC and its +private subnets. + + + +Now press the Launch a Cache Cluster and choose Redis for our +DB engine. You'll be able to configure details such as replication, +Multi AZ and node types. The second section will allow us to choose our +subnet and security group and + + + + + +*** + +## Elastic File System + +This new AWS offering allows us to create a file system accessible by
+EC2 instances within a VPC. Choose our VPC and the subnets will be +
automatically configured assuming we don't need to set explicit IPs. +The
next section allows us to add tags and choose between General +Purpose or
Max I/O which is a good option when being accessed by a +large number of
EC2 instances. + +
 + +To actually mount and install the NFS client we'll use the User Data +section when adding our Launch Configuration. + +*** + +## Initiate AMI + +We are going to launch an EC2 instance and bake an image so that we can +later use it for auto scaling. We'll also take this opportunity to add an +extension to our RDS through this temporary EC2 instance. + +### EC2 Instance + +Look for the EC2 option and choose to create an instance. We'll need at +least a t2.medium type and for this article we'll choose an Ubuntu 14.04 +HVM 64-bit. In the Configure Instance section choose our GitLab VPC and +a public subnet. I'd choose at least 10GB of storage. + +In the security group we'll create a new one considering that we need to +SSH into the instance and also try it out through http. So let's add the +http traffic from anywhere and name it something such as +`gitlab-ec2-security-group`. + +While we wait for it to launch we can allocate an Elastic IP and +associate it with our new EC2 instance. + +### RDS and Redis Security Group + +After the instance is being created we will navigate to our EC2 security +groups and add a small change for our EC2 instances to be able to +connect to RDS. First copy the security group name we just defined, +namely `gitlab-ec2-security-group`, and edit select the RDS security +group and edit the inbound rules. Choose the rule type to be PostgreSQL +and paste the name under source. + + + +Similar to the above we'll jump to the `gitlab-ec2-security-group` group +and add a custom TCP rule for port 6379 accessible within itself. + +### Install GitLab + +To connect through SSH you will need to have the `pem` file which you +chose available and with the correct permissions such as `400`. + +After accessing your server don't forget to update and upgrade your +packages. + + sudo apt-get update && sudo apt-get upgrade -y + +Then follow installation instructions from +[GitLab](https://about.gitlab.com/downloads-ee/#ubuntu1404), but before +running reconfigure we need to make sure all our services are tied down +so just leave the reconfigure command until after we edit our gitlab.rb +file. + + +### Extension for PostgreSQL + +Connect to your new RDS instance to verify access and to install +a required extension. We can find the host or endpoint by selecting the +instance and we just created and after the details drop down we'll find +it labeled as 'Endpoint'; do remember not to include the colon and port +number. + + sudo /opt/gitlab/embedded/bin/psql -U gitlab -h <rds-endpoint> -d gitlabhq_production + psql (9.4.7) + Type "help" for help. + + gitlab=# CREATE EXTENSION pg_trgm; + gitlab=# \q + +### Configure GitLab + +While connected to your server edit the `gitlab.rb` file at `/etc/gitlab/gitlab.rb` +find the `external_url 'http://gitlab.example.com'` option and change it +to the domain you will be using or the public IP address of the current +instance to test the configuration. + +For a more detailed description about configuring GitLab read [Configuring GitLab for HA](http://docs.gitlab.com/ee/administration/high_availability/gitlab.html) + +Now look for the GitLab database settings and uncomment as necessary. In +our current case we'll specify the adapter, encoding, host, db name, +username, and password. + + gitlab_rails['db_adapter'] = "postgresql" + gitlab_rails['db_encoding'] = "unicode" + gitlab_rails['db_database'] = "gitlabhq_production" + gitlab_rails['db_username'] = "gitlab" + gitlab_rails['db_password'] = "mypassword" + gitlab_rails['db_host'] = "<rds-endpoint>" + +Next we only need to configure the Redis section by adding the host and +uncommenting the port. + + + +The last configuration step is to [change the default file locations ](http://docs.gitlab.com/ee/administration/high_availability/nfs.html) +to make the EFS integration easier to manage. + + gitlab_rails['redis_host'] = "<redis-endpoint>" + gitlab_rails['redis_port'] = 6379 + +Finally run reconfigure, you might find it useful to run a check and +a service status to make sure everything has been setup correctly. + + sudo gitlab-ctl reconfigure + sudo gitlab-rake gitlab:check + sudo gitlab-ctl status + +If everything looks good copy the Elastic IP over to your browser and +test the instance manually. + +### AMI + +After you finish testing your EC2 instance go back to its dashboard and +while the instance is selected press on the Actions dropdown to choose +Image -> Create an Image. Give it a name and description and confirm. + +*** + +## Load Balancer + +On the same dashboard look for Load Balancer on the left column and press +the Create button. Choose a classic Load Balancer, our gitlab VPC, not +internal and make sure its listening for HTTP and HTTPS on port 80. + +Here is a tricky part though, when adding subnets we need to associate +public subnets instead of the private ones where our instances will +actually live. + +On the secruity group section let's create a new one named +`gitlab-loadbalancer-sec-group` and allow both HTTP ad HTTPS traffic +from anywhere. + +The Load Balancer Health will allow us to indicate where to ping and what +makes up a healthy or unhealthy instance. + +We won't add the instance on the next session because we'll destroy it +momentarily as we'll be using the image we where creating. We will keep +the Enable Cross-Zone and Enable Connection Draining active. + +After we finish creating the Load Balancer we can re visit our Security +Groups to improve access only through the ELB and any other requirement +you might have. + +*** + +## Auto Scaling Group + +Our AMI should be done by now so we can start working on our Auto +Scaling Group. + +This option is also available through the EC2 dashboard on the left +sidebar. Press on the create button. Select the new image on My AMIs and +give it a `t2.medium` size. To be able to use Elastic File System we need +to add a script to mount EFS automatically at launch. We'll do this at +the Advanced Details section where we have a [User Data](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html) +text area that allows us to add a lot of custom configurations which +allows you to add a custom script for when launching an instance. Let's +add the following script to the User Data section: + + + #cloud-config + package_upgrade: true + packages: + - nfs-common + runcmd: + - mkdir -p /gitlab-data + - chown ec2-user:ec2-user /gitlab-data + - echo "$(curl --silent http://169.254.169.254/latest/meta-data/placement/availability-zone).file-system-id.aws-region.amazonaws.com:/ /gitlab-data nfs defaults,vers=4.1 0 0" >> /etc/fstab + - mount -a -t nfs + - sudo gitlab-ctl reconfigure + +On the security group section we can chosse our existing +`gitlab-ec2-security-group` group which has already been tested. + +After this is launched we are able to start creating our Auto Scaling +Group. Start by giving it a name and assinging it our VPC and private +subnets. We also want to always start with two instances and if you +scroll down to Advanced Details we can choose to receive traffic from ELBs. +Lets enable that option and select our ELB. We also want to use the ELB's +health check. + + + +### Policies + +This is the really great part of Auto Scaling, we get to choose when AWS +launches new instances and when it removes them. For this group we'll +scale between 2 and 4 instances where one instance will be added if CPU +utilization is greater than 60% and one instance is removed if it falls +to less than 45%. Here are the complete policies: + + + +You'll notice that after we save this AWS starts launching our two +instances in different AZs and without a public IP which is exactly what +we where aiming for. + +*** + +## Final Thoughts + +After you're done with the policies section have some fun trying to break +instances. You should be able to see how the Auto Scaling Group and the +EC2 screen start bringing them up again. + +High Availability is a very big area, we went mostly through scaling and +some redundancy options but it might also imply Geographic replication. +There is a lot of ground yet to cover so have a read through these other +resources and feel free to open an issue to request additional material. + + * [GitLab High Availability](http://docs.gitlab.com/ce/administration/high_availability/README.html#sts=High Availability) + * [GitLab Geo](http://docs.gitlab.com/ee/gitlab-geo/README.html) diff --git a/doc/university/high-availability/aws/img/auto-scaling-det.png b/doc/university/high-availability/aws/img/auto-scaling-det.png Binary files differnew file mode 100644 index 00000000000..e9b65529495 --- /dev/null +++ b/doc/university/high-availability/aws/img/auto-scaling-det.png diff --git a/doc/university/high-availability/aws/img/db-subnet-group.png b/doc/university/high-availability/aws/img/db-subnet-group.png Binary files differnew file mode 100644 index 00000000000..0768aa73c45 --- /dev/null +++ b/doc/university/high-availability/aws/img/db-subnet-group.png diff --git a/doc/university/high-availability/aws/img/ec-subnet.png b/doc/university/high-availability/aws/img/ec-subnet.png Binary files differnew file mode 100644 index 00000000000..f41d78b271d --- /dev/null +++ b/doc/university/high-availability/aws/img/ec-subnet.png diff --git a/doc/university/high-availability/aws/img/elastic-file-system.png b/doc/university/high-availability/aws/img/elastic-file-system.png Binary files differnew file mode 100644 index 00000000000..7de866d1e89 --- /dev/null +++ b/doc/university/high-availability/aws/img/elastic-file-system.png diff --git a/doc/university/high-availability/aws/img/ig-rt.png b/doc/university/high-availability/aws/img/ig-rt.png Binary files differnew file mode 100644 index 00000000000..93bb0c2ae02 --- /dev/null +++ b/doc/university/high-availability/aws/img/ig-rt.png diff --git a/doc/university/high-availability/aws/img/ig.png b/doc/university/high-availability/aws/img/ig.png Binary files differnew file mode 100644 index 00000000000..cc50456370f --- /dev/null +++ b/doc/university/high-availability/aws/img/ig.png diff --git a/doc/university/high-availability/aws/img/instance_specs.png b/doc/university/high-availability/aws/img/instance_specs.png Binary files differnew file mode 100644 index 00000000000..ef31dc41dae --- /dev/null +++ b/doc/university/high-availability/aws/img/instance_specs.png diff --git a/doc/university/high-availability/aws/img/new_vpc.png b/doc/university/high-availability/aws/img/new_vpc.png Binary files differnew file mode 100644 index 00000000000..4aac6af7c7a --- /dev/null +++ b/doc/university/high-availability/aws/img/new_vpc.png diff --git a/doc/university/high-availability/aws/img/policies.png b/doc/university/high-availability/aws/img/policies.png Binary files differnew file mode 100644 index 00000000000..8c58117e4fa --- /dev/null +++ b/doc/university/high-availability/aws/img/policies.png diff --git a/doc/university/high-availability/aws/img/rds-net-opt.png b/doc/university/high-availability/aws/img/rds-net-opt.png Binary files differnew file mode 100644 index 00000000000..bc204de2474 --- /dev/null +++ b/doc/university/high-availability/aws/img/rds-net-opt.png diff --git a/doc/university/high-availability/aws/img/rds-sec-group.png b/doc/university/high-availability/aws/img/rds-sec-group.png Binary files differnew file mode 100644 index 00000000000..8864dc3e463 --- /dev/null +++ b/doc/university/high-availability/aws/img/rds-sec-group.png diff --git a/doc/university/high-availability/aws/img/redis-cluster-det.png b/doc/university/high-availability/aws/img/redis-cluster-det.png Binary files differnew file mode 100644 index 00000000000..9e9a81283c5 --- /dev/null +++ b/doc/university/high-availability/aws/img/redis-cluster-det.png diff --git a/doc/university/high-availability/aws/img/redis-net.png b/doc/university/high-availability/aws/img/redis-net.png Binary files differnew file mode 100644 index 00000000000..037bd6d6897 --- /dev/null +++ b/doc/university/high-availability/aws/img/redis-net.png diff --git a/doc/university/high-availability/aws/img/route_table.png b/doc/university/high-availability/aws/img/route_table.png Binary files differnew file mode 100644 index 00000000000..1dea322474d --- /dev/null +++ b/doc/university/high-availability/aws/img/route_table.png diff --git a/doc/university/high-availability/aws/img/subnet.png b/doc/university/high-availability/aws/img/subnet.png Binary files differnew file mode 100644 index 00000000000..dbc71201992 --- /dev/null +++ b/doc/university/high-availability/aws/img/subnet.png diff --git a/doc/university/process/README.md b/doc/university/process/README.md new file mode 100644 index 00000000000..7ff53c2cc3f --- /dev/null +++ b/doc/university/process/README.md @@ -0,0 +1,30 @@ +--- +title: University | Process +--- + +## Suggesting improvements + +If you would like to teach a class or participate or help in any way please +submit a merge request and assign it to [Job](https://gitlab.com/u/JobV). + +If you have suggestions for additional courses you would like to see, +please submit a merge request to add an upcoming class, assign to +[Chad](https://gitlab.com/u/chadmalchow) and /cc [Job](https://gitlab.com/u/JobV). + +## Adding classes + +1. All training materials of any kind should be added to [GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/) + to ensure they are available to a broad audience (don't use any other repo or + storage for training materials). +1. Don't make materials that are needlessly specific to one group of people, try + to keep the wording broad and inclusive (don't make things for only GitLab Inc. + people, only interns, only customers, etc.). +1. To allow people to contribute all content should be in git. +1. The content can go in a subdirectory under `/doc/university/`. +1. To make, view or modify the slides of the classes use [Deckset](http://www.decksetapp.com/) + or [RevealJS](http://lab.hakim.se/reveal-js/). Do not use Powerpoint or Google + Slides since this prevents everyone from contributing. +1. Please upload any video recordings to our Youtube channel. We prefer them to + be public, if needed they can be unlisted but if so they should be linked from + this page. +1. Please create a merge request and assign to [SeanPackham](https://gitlab.com/u/SeanPackham). diff --git a/doc/university/support/README.md b/doc/university/support/README.md new file mode 100644 index 00000000000..da991e56370 --- /dev/null +++ b/doc/university/support/README.md @@ -0,0 +1,188 @@ + +## Support Boot Camp + +**Goal:** Prepare new Service Engineers at GitLab + +For each stage there are learning goals and content to support the learning of the engineer. +The goal of this boot camp is to have every Service Engineer prepared to help our customers +with whatever needs they might have and to also assist our awesome community with their +questions. + +Always start with the [University Overview](../README.md) and then work +your way here for more advanced and specific training. Once you feel comfortable +with the topics of the current stage, move to the next. + +### Stage 1 + +Follow the topics on the [University Overview](../README.md), concentrate on it +during your first Stage, but also: + +- Perform the [first steps](https://about.gitlab.com/handbook/support/onboarding/#first-steps) of + the on-boarding process for new Service Engineers + +#### Goals + +Aim to have a good overview of the Product and main features, Git and the Company + +### Stage 2 + +Continue to look over remaining portions of the [University Overview](../README.md) and continue on to these topics: + +#### Set up your development machine + +Get your development machine ready to familiarize yourself with the codebase, the components, and to be prepared to reproduce issues that our users encounter + +- Install the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) + - [Setup OpenLDAP as part of this](https://gitlab.com/gitlab-org/gitlab-development-kit#openldap) + +#### Become comfortable with the Installation processes that we support + +It's important to understand how to install GitLab in the same way that our users do. Try installing different versions and upgrading and downgrading between them. Installation from source will give you a greater understanding of the components that we employ and how everything fits together. + +Sometimes we need to upgrade customers from old versions of GitLab to latest, so it's good to get some experience of doing that now. + +- [Installation Methods](https://about.gitlab.com/installation/): + - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/) + - [Docker](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/docker) + - [Source](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md) +- Get yourself a Digital Ocean droplet, where you can install and maintain your own instance of GitLab + - Ask in #infrastructure about this + - Populate with some test data + - Keep this up-to-date as patch and version releases become available, just like our customers would +- Try out the following installation path + - [Install GitLab 4.2 from source](https://gitlab.com/gitlab-org/gitlab-ce/blob/d67117b5a185cfb15a1d7e749588ff981ffbf779/doc/install/installation.md) + - External MySQL database + - External NGINX + - Create some test data + - Populated Repos + - Users + - Groups + - Projects + - [Backup using our Backup rake task](http://docs.gitlab.com/ce/raketasks/backup_restore.html#create-a-backup-of-the-gitlab-system) + - [Upgrade to 5.0 source using our Upgrade documentation](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/4.2-to-5.0.md) + - [Upgrade to 5.1 source](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/5.0-to-5.1.md) + - [Upgrade to 6.0 source](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/5.1-to-6.0.md) + - [Upgrade to 7.14 source](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/update/6.x-or-7.x-to-7.14.md) + - [Backup using our Backup rake task](http://docs.gitlab.com/ce/raketasks/backup_restore.html#create-a-backup-of-the-gitlab-system) + - [Perform the MySQL to PostgreSQL migration to convert your backup](http://docs.gitlab.com/ce/update/mysql_to_postgresql.html#converting-a-gitlab-backup-file-from-mysql-to-postgres) + - [Upgrade to Omnibus 7.14](http://doc.gitlab.com/omnibus/update/README.html#upgrading-from-a-non-omnibus-installation-to-an-omnibus-installation) + - [Restore backup using our Restore rake task](http://docs.gitlab.com/ce/raketasks/backup_restore.html#restore-a-previously-created-backup) + - [Upgrade to latest EE](https://about.gitlab.com/downloads-ee) + - (GitLab inc. only) Acquire and apply a license for the Enterprise Edition product, ask in #support +- Perform a downgrade from [EE to CE](http://doc.gitlab.com/ee/downgrade_ee_to_ce/README.html) + +#### Start to learn about some of the integrations that we support + +Our integrations add great value to GitLab. User questions often relate to integrating GitLab with existing external services and the configuration involved + +- Learn about our Integrations (specially, not only): + - [LDAP](http://doc.gitlab.com/ee/integration/ldap.html) + - [JIRA](http://doc.gitlab.com/ee/project_services/jira.html) + - [Jenkins](http://doc.gitlab.com/ee/integration/jenkins.html) + - [SAML](http://doc.gitlab.com/ce/integration/saml.html) + +#### Goals + +- Aim to be comfortable with installation of the GitLab product and configuration of some of the major integrations +- Aim to have an installation available for reproducing customer reports + +### Stage 3 + +#### Understand the gathering of diagnostics for GitLab instances + +- Learn about the GitLab checks that are available + - [Environment Information and maintenance checks](http://docs.gitlab.com/ce/raketasks/maintenance.html) + - [GitLab check](http://docs.gitlab.com/ce/raketasks/check.html) + - Omnibus commands + - [Status](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#get-service-status) + - [Starting and stopping services](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#starting-and-stopping) + - [Starting a rails console](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/maintenance/README.md#invoking-rake-tasks) + +#### Learn about the Support process + +Zendesk is our Support Centre and our main communication line with our Customers. We communicate with customers through several other channels too + +- Familiarize yourself with ZenDesk + - [UI Overview](https://support.zendesk.com/hc/en-us/articles/203661806-Introduction-to-the-Zendesk-agent-interface) + - [Updating Tickets](https://support.zendesk.com/hc/en-us/articles/212530318-Updating-and-solving-tickets) + - [Working w/ Tickets](https://support.zendesk.com/hc/en-us/articles/203690856-Working-with-tickets) *Read: avoiding agent collision.* +- Dive into our ZenDesk support process by reading how to [handle tickets](https://about.gitlab.com/handbook/support/onboarding/#handling-tickets) +- Start getting real world experience by handling real tickets, all the while gaining further experience with the Product. + - First, learn about our [Support Channels](https://about.gitlab.com/handbook/support/#support-channels) + - Ask other Service Engineers for help, when necessary, and to review your responses + - Start with [StackOverflow](https://about.gitlab.com/handbook/support/#stack-overflowa-namestack-overflowa) and the [GitLab forum](https://about.gitlab.com/handbook/support/#foruma-namegitlab-foruma) + - Here you will find a large variety of queries mainly from our Users who are self hosting GitLab CE + - Understand the questions that are asked and dig in to try to find a solution + - [Proceed on to the GitLab.com Support Forum](https://about.gitlab.com/handbook/support/#gitlabcom-support-trackera-namesupp-foruma) + - Here you will find queries regarding our own GitLab.com + - Helping Users here will give you an understanding of our Admin interface and other tools + - [Proceed on to the Twitter tickets in Zendesk](https://about.gitlab.com/handbook/support/#twitter) + - Here you will gain a great insight into our userbase + - Learn from any complaints and problems and feed them back to the team + - Tweets can range from help needed with GitLab installations, the API and just general queries + - [Proceed on to Regular email Support tickets](https://about.gitlab.com/handbook/support/#regular-zendesk-tickets-a-nameregulara) + - Here you will find tickets from our GitLab EE Customers and GitLab CE Users + - Tickets here are extremely varied and often very technical + - You should be prepared for these tickets, given the knowledge gained from previous tiers and your training +- Check out your colleagues' responses + - Hop on to the #support-live-feed channel in Slack and see the tickets as they come in and are updated + - Read through old tickets that your colleagues have worked on +- Start arranging to pair on calls with other Service Engineers. Aim to cover a few of each type of call + - [Learn about Cisco WebEx](https://about.gitlab.com/handbook/support/onboarding/#webexa-namewebexa) + - Training calls + - Information gathering calls + - It's good to find out how new and prospective customers are going to be using the product and how they will set up their infrastructure + - Diagnosis calls + - When email isn't enough we may need to hop on a call and do some debugging along side the customer + - These paired calls are a great learning experience + - Upgrade calls + - Emergency calls + +#### Learn about the Escalation process for tickets + +Some tickets need specific knowledge or a deep understanding of a particular component and will need to be escalated to a Senior Service Engineer or Developer + +- Read about [Escalation](https://about.gitlab.com/handbook/support/onboarding/#create-issuesa-namecreate-issuea) +- Find the macros in Zendesk for ticket escalations +- Take a look at the [GitLab.com Team page](https://about.gitlab.com/team/) to find the resident experts in their fields + +#### Learn about raising issues and fielding feature proposals + +- Understand what's in the pipeline and proposed features at GitLab: [Direction Page](https://about.gitlab.com/direction/) +- Practice searching issues and filtering using [labels](https://gitlab.com/gitlab-org/gitlab-ce/labels) to find existing feature proposals and bugs +- If raising a new issue always provide a relevant label and a link to the relevant ticket in Zendesk +- Add [customer labels](https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name%5B%5D=customer) for those issues relevant to our subscribers +- Take a look at the [existing issue templates](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#issue-tracker) to see what is expected +- Raise issues for bugs in a manner that would make the issue easily reproducible. A Developer or a contributor may work on your issue + +#### Goals + +- Aim to have a good understanding of the problems that customers are facing +- Aim to have gained experience in scheduling and participating in calls with customers +- Aim to have a good understanding of ticket flow through Zendesk and how to interat with our various channels + +### Stage 4 + +#### Advanced GitLab topics + +Move on to understanding some of GitLab's more advanced features. You can make use of GitLab.com to understand the features from an end-user perspective and then use your own instance to understand setup and configuration of the feature from an Administrative perspective + +- Set up and try [Git Annex](http://doc.gitlab.com/ee/workflow/git_annex.html) +- Set up and try [Git LFS](http://doc.gitlab.com/ee/workflow/lfs/manage_large_binaries_with_git_lfs.html) +- Get to know the [GitLab API](http://doc.gitlab.com/ee/api/README.html), its capabilities and shortcomings +- Learn how to [migrate from SVN to Git](http://doc.gitlab.com/ee/workflow/importing/migrating_from_svn.html) +- Set up [GitLab CI](http://doc.gitlab.com/ee/ci/quick_start/README.html) +- Create your first [GitLab Page](http://doc.gitlab.com/ee/pages/administration.html) +- Get to know the GitLab Codebase by reading through the source code: + - Find the differences between the [EE codebase](https://gitlab.com/gitlab-org/gitlab-ce) + and the [CE codebase](https://gitlab.com/gitlab-org/gitlab-ce) +- Ask as many questions as you can think of on the `#support` chat channel + +#### Get initiated for on-call duty + +- Read over the [public run-books to understand common tasks](https://gitlab.com/gitlab-com/runbooks) +- Create an issue on the internal Organization tracker to schedule time with the DevOps / Production team, so that you learn how to handle GitLab.com going down. Once you are trained for this, you are ready to be added to the on-call rotation. + +#### Goals + +- Aim to become a fully-fledged Service Engineer! diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md new file mode 100644 index 00000000000..03c62a81b10 --- /dev/null +++ b/doc/university/training/end-user/README.md @@ -0,0 +1,420 @@ + +# Training + +This training material is the markdown used to generate training slides +which can be found at [End User Slides](https://gitlab-org.gitlab.io/end-user-training-slides/#/) +through it's [RevealJS](https://gitlab.com/gitlab-org/end-user-training-slides) +project. + +--- + +## Git Intro + +--- + +### What is a Version Control System (VCS) + +- Records changes to a file +- Maintains history of changes +- Disaster Recovery +- Types of VCS: Local, Centralized and Distributed + +--- + +### Short Story of Git + +- 1991-2002: The Linux kernel was being maintaned by sharing archived files + and patches. +- 2002: The Linux kernel project began using a DVCS called BitKeeper +- 2005: BitKeeper revoked the free-of-charge status and Git was created + +--- + +### What is Git + +- Distributed Version Control System +- Great branching model that adapts well to most workflows +- Fast and reliable +- Keeps a complete history +- Disaster recovery friendly +- Open Source + +--- + +### Getting Help + +- Use the tools at your disposal when you get stuck. + - Use `git help <command>` command + - Use Google (i.e. StackOverflow, Google groups) + - Read documentation at https://git-scm.com + +--- + +## Git Setup +Workshop Time! + +--- + +### Setup + +- Windows: Install 'Git for Windows' + - https://git-for-windows.github.io +- Mac: Type `git` in the Terminal application. + - If it's not installed, it will prompt you to install it. +- Linux + - Debian: `sudo apt-get install git-all` + - Red Hat `sudo yum install git-all` + +--- + +### Configure + +- One-time configuration of the Git client: + +```bash +git config --global user.name "Your Name" +git config --global user.email you@example.com +``` + +- If you don't use the global flag you can setup a different author for + each project +- Check settings with: + +```bash +git config --global --list +``` +- You might want or be required to use an SSH key. + - Instructions: [SSH](http://doc.gitlab.com/ce/ssh/README.html) + +--- + +### Workspace + +- Choose a directory on you machine easy to access +- Create a workspace or development directory +- This is where we'll be working and adding content + +--- + +```bash +mkdir ~/development +cd ~/development + +-or- + +mkdir ~/workspace +cd ~/workspace +``` + +--- + +## Git Basics + +--- + +### Git Workflow + +- Untracked files + - New files that Git has not been told to track previously. +- Working area (Workspace) + - Files that have been modified but are not committed. +- Staging area (Index) + - Modified files that have been marked to go in the next commit. +- Upstream + - Hosted repository on a shared server + +--- + +### GitLab + +- GitLab is an application to code, test and deploy. +- Provides repository management with access controls, code reviews, + issue tracking, Merge Requests, and other features. +- The hosted version of GitLab is gitlab.com + +--- + +### New Project + +- Sign in into your gitlab.com account +- Create a project +- Choose to import from 'Any Repo by URL' and use https://gitlab.com/gitlab-org/training-examples.git +- On your machine clone the `training-examples` project + +--- + +### Git and GitLab basics + +1. Edit `edit_this_file.rb` in `training-examples` +2. See it listed as a changed file (working area) +3. View the differences +4. Stage the file +5. Commit +6. Push the commit to the remote +7. View the git log + +--- + +```shell +# Edit `edit_this_file.rb` +git status +git diff +git add <file> +git commit -m 'My change' +git push origin master +git log +``` + +--- + +### Feature Branching + +1. Create a new feature branch called `squash_some_bugs` +2. Edit `bugs.rb` and remove all the bugs. +3. Commit +4. Push + +--- + +```shell +git checkout -b squash_some_bugs +# Edit `bugs.rb` +git status +git add bugs.rb +git commit -m 'Fix some buggy code' +git push origin squash_some_bugs +``` + +--- + +## Merge Request + +--- + +### Merge requests + +- When you want feedback create a merge request +- Target is the ‘default’ branch (usually master) +- Assign or mention the person you would like to review +- Add `WIP` to the title if it's a work in progress +- When accepting, always delete the branch +- Anyone can comment, not just the assignee +- Push corrections to the same branch + + +--- + +### Merge request example + +- Create your first merge request + - Use the blue button in the activity feed + - View the diff (changes) and leave a comment + - Push a new commit to the same branch + - Review the changes again and notice the update + +--- + +### Feedback and Collaboration + +- Merge requests are a time for feedback and collaboration +- Giving feedback is hard +- Be as kind as possible +- Receiving feedback is hard +- Be as receptive as possible +- Feedback is about the best code, not the person. You are not your code +- Feedback and Collaboration + +--- + +### Feedback and Collaboration + +- Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:[Thoughtbot](https://github.com/thoughtbot/guides/tree/master/code-review) +- See GitLab merge requests for examples: [Merge Requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests) + +--- + +## Merge Conflicts + +--- + +### Merge Conflicts +* Happen often +* Learning to fix conflicts is hard +* Practice makes perfect +* Force push after fixing conflicts. Be careful! + +--- + +### Example Plan +1. Checkout a new branch and edit conflicts.rb. Add 'Line4' and 'Line5'. +2. Commit and push +3. Checkout master and edit conflicts.rb. Add 'Line6' and 'Line7' below 'Line3'. +4. Commit and push to master +5. Create a merge request and watch it fail +6. Rebase our new branch with master +7. Fix conflicts on the conflicts.rb file. +8. Stage the file and continue rebasing +9. Force push the changes +10. Finally continue with the Merge Request + +--- + +### Example 1/2 + + git checkout -b conflicts_branch + + # vi conflicts.rb + # Add 'Line4' and 'Line5' + + git commit -am "add line4 and line5" + git push origin conflicts_branch + + git checkout master + + # vi conflicts.rb + # Add 'Line6' and 'Line7' + git commit -am "add line6 and line7" + git push origin master + +--- + +### Example 2/2 + +Create a merge request on the GitLab web UI. You'll see a conflict warning. + + git checkout conflicts_branch + git fetch + git rebase master + + # Fix conflicts by editing the files. + + git add conflicts.rb + # No need to commit this file + + git rebase --continue + + # Remember that we have rewritten our commit history so we + # need to force push so that our remote branch is restructured + git push origin conflicts_branch -f + +--- + +### Notes + +* When to use `git merge` and when to use `git rebase` +* Rebase when updating your branch with master +* Merge when bringing changes from feature to master +* Reference: https://www.atlassian.com/git/tutorials/merging-vs-rebasing/ + +--- + +## Revert and Unstage + +--- + +### Unstage + +To remove files from stage use reset HEAD. Where HEAD is the last commit of the current branch: + + git reset HEAD <file> + +This will unstage the file but maintain the modifications. To revert the file back to the state it was in before the changes we can use: + + git checkout -- <file> + +To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag: + + git rm '*.txt' + git rm -r <dirname> + +If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our .gitignore file then use `--cache`: + + git rm <filename> --cache + +--- + +### Undo Commits + +Undo last commit putting everything back into the staging area: + + git reset --soft HEAD^ + +Add files and change message with: + + git commit --amend -m "New Message" + +Undo last and remove changes + + git reset --hard HEAD^ + +Same as last one but for two commits back: + + git reset --hard HEAD^^ + +Don't reset after pushing + +--- + +### Reset Workflow + +1. Edit file again 'edit_this_file.rb' +2. Check status +3. Add and commit with wrong message +4. Check log +5. Amend commit +6. Check log +7. Soft reset +8. Check log +9. Pull for updates +10. Push changes + +---- + + # Change file edit_this_file.rb + git status + git commit -am "kjkfjkg" + git log + git commit --amend -m "New comment added" + git log + git reset --soft HEAD^ + git log + git pull origin master + git push origin master + +--- + +### Note + +git revert vs git reset +Reset removes the commit while revert removes the changes but leaves the commit +Revert is safer considering we can revert a revert + + + # Changed file + git commit -am "bug introduced" + git revert HEAD + # New commit created reverting changes + # Now we want to re apply the reverted commit + git log # take hash from the revert commit + git revert <rev commit hash> + # reverted commit is back (new commit created again) + +--- + +## Questions + +--- + +## Instructor Notes + +--- + +### Version Control + - Local VCS was used with a filesystem or a simple db. + - Centralized VCS such as Subversion includes collaboration but + still is prone to data loss as the main server is the single point of + failure. + - Distributed VCS enables the team to have a complete copy of the project + and work with little dependency to the main server. In case of a main + server failing the project can be recovered by any of the latest copies + from the team diff --git a/doc/user/markdown.md b/doc/user/markdown.md index c7fda8a497f..56e5b802a52 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -27,6 +27,7 @@ * [Horizontal Rule](#horizontal-rule) * [Line Breaks](#line-breaks) * [Tables](#tables) +* [Footnotes](#footnotes) **[Wiki-Specific Markdown](#wiki-specific-markdown)** @@ -699,6 +700,15 @@ By including colons in the header row, you can align the text within that column | Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | | Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +## Footnotes + +You can add footnotes to your text as follows.[^1] +[^1]: This is my awesome footnote. + +``` +You can add footnotes to your text as follows.[^1] +[^1]: This is my awesome footnote. +``` ## Wiki-specific Markdown |
