25 |
26 |
27 |
--------------------------------------------------------------------------------
/.github/actions/check-history-action/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "check-history-action",
3 | "version": "1.0.0",
4 | "description": "Local exercise action to verify the desire commit was removed",
5 | "main": "index.js",
6 | "scripts": {
7 | "test": "echo \"Error: no test specified\" && exit 1",
8 | "build": "ncc build main.js"
9 | },
10 | "repository": {
11 | "type": "git",
12 | "url": "git+https://github.com/githubtraining/exercise-remove-commit-history.git"
13 | },
14 | "author": "githubtraining",
15 | "license": "MIT",
16 | "bugs": {
17 | "url": "https://github.com/githubtraining/exercise-remove-commit-history/issues"
18 | },
19 | "homepage": "https://github.com/githubtraining/exercise-remove-commit-history#readme",
20 | "dependencies": {
21 | "@actions/core": "^1.4.0",
22 | "@actions/github": "^5.0.0"
23 | }
24 | }
25 |
--------------------------------------------------------------------------------
/.github/workflows/grading.yml:
--------------------------------------------------------------------------------
1 | name: Grading workflow
2 | on:
3 | push:
4 |
5 | workflow_dispatch:
6 |
7 | jobs:
8 | grade-learner:
9 | if: github.event_name == 'push' && github.repository != 'githubtraining/exercise-remove-commit-history' && github.event.commits[0].message != 'Initial commit'
10 | runs-on: ubuntu-latest
11 | steps:
12 | - uses: actions/checkout@v2
13 | - name: Grade gitignore activity
14 | id: events
15 | uses: ./.github/actions/check-history-action
16 | with:
17 | token: ${{ secrets.GITHUB_TOKEN }}
18 |
19 | - name: Grading results
20 | uses: githubtraining/looking-glass-action@v0.2.0
21 | with:
22 | github-token: ${{ secrets.GITHUB_TOKEN }}
23 | feedback: ${{ steps.events.outputs.reports }}
24 |
25 | troubleshoot-activity:
26 | if: github.event_name == 'workflow_dispatch'
27 | runs-on: ubuntu-latest
28 | steps:
29 | - name: troubleshooting steps
30 | run: echo "If you're stuck, this documentation may be helpful; https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository"
31 |
--------------------------------------------------------------------------------
/.github/actions/check-history-action/lib/gradeLearner.js:
--------------------------------------------------------------------------------
1 | const github = require("@actions/github");
2 | const core = require("@actions/core");
3 |
4 | module.exports = async () => {
5 | const token = core.getInput("token");
6 | const octokit = github.getOctokit(token);
7 |
8 | try {
9 | const res = await octokit.rest.repos.listCommits({
10 | ...github.context.repo,
11 | });
12 | const commitSHAs = res.data.map((c) => c.sha);
13 |
14 | const badSHAs = [];
15 | for (const sha of commitSHAs) {
16 | const tree = await octokit.rest.git.getTree({
17 | ...github.context.repo,
18 | tree_sha: sha,
19 | recursive: 1,
20 | });
21 |
22 | if (tree.data.tree.some((t) => t.path === ".env")) badSHAs.push(sha);
23 | }
24 |
25 | if (badSHAs.length === 0) {
26 | return {
27 | reports: [
28 | {
29 | filename: "",
30 | isCorrect: true,
31 | display_type: "actions",
32 | level: "info",
33 | msg: "Great job! You have successfully removed the sensitive info from this repo.",
34 | error: {
35 | expected: "",
36 | got: "",
37 | },
38 | },
39 | ],
40 | };
41 | } else {
42 | return {
43 | reports: [
44 | {
45 | filename: "",
46 | isCorrect: false,
47 | display_type: "actions",
48 | level: "warning",
49 | msg: `incorrect solution`,
50 | error: {
51 | expected: "All references to the .env file to be removed",
52 | got: `.env is still referenced in these commits: ${badSHAs}`,
53 | },
54 | },
55 | ],
56 | };
57 | }
58 | } catch (error) {
59 | return {
60 | reports: [
61 | {
62 | filename: filename,
63 | isCorrect: false,
64 | display_type: "actions",
65 | level: "fatal",
66 | msg: "",
67 | error: {
68 | expected: "",
69 | got: "An internal error occurred. Please open an issue at: https://github.com/githubtraining/exercise-remove-commit-history and let us know! Thank you",
70 | },
71 | },
72 | ],
73 | };
74 | }
75 | };
76 |
--------------------------------------------------------------------------------
/style.css:
--------------------------------------------------------------------------------
1 | * {
2 | box-sizing: border-box;
3 | }
4 |
5 | /* Set a background color */
6 | body {
7 | background-color: #474e5d;
8 | font-family: Helvetica, sans-serif;
9 | }
10 |
11 | /* The actual timeline (the vertical ruler) */
12 | .timeline {
13 | position: relative;
14 | max-width: 1200px;
15 | margin: 0 auto;
16 | }
17 |
18 | /* The actual timeline (the vertical ruler) */
19 | .timeline::after {
20 | content: "";
21 | position: absolute;
22 | width: 6px;
23 | background-color: white;
24 | top: 0;
25 | bottom: 0;
26 | left: 50%;
27 | margin-left: -3px;
28 | }
29 |
30 | /* Container around content */
31 | .container {
32 | padding: 10px 40px;
33 | position: relative;
34 | background-color: inherit;
35 | width: 50%;
36 | }
37 |
38 | /* The circles on the timeline */
39 | .container::after {
40 | content: "";
41 | position: absolute;
42 | width: 25px;
43 | height: 25px;
44 | right: -17px;
45 | background-color: white;
46 | border: 4px solid #ff9f55;
47 | top: 15px;
48 | border-radius: 50%;
49 | z-index: 1;
50 | }
51 |
52 | /* Place the container to the left */
53 | .left {
54 | left: 0;
55 | }
56 |
57 | /* Place the container to the right */
58 | .right {
59 | left: 50%;
60 | }
61 |
62 | /* Add arrows to the left container (pointing right) */
63 | .left::before {
64 | content: " ";
65 | height: 0;
66 | position: absolute;
67 | top: 22px;
68 | width: 0;
69 | z-index: 1;
70 | right: 30px;
71 | border: medium solid white;
72 | border-width: 10px 0 10px 10px;
73 | border-color: transparent transparent transparent white;
74 | }
75 |
76 | /* Add arrows to the right container (pointing left) */
77 | .right::before {
78 | content: " ";
79 | height: 0;
80 | position: absolute;
81 | top: 22px;
82 | width: 0;
83 | z-index: 1;
84 | left: 30px;
85 | border: medium solid white;
86 | border-width: 10px 10px 10px 0;
87 | border-color: transparent white transparent transparent;
88 | }
89 |
90 | /* Fix the circle for containers on the right side */
91 | .right::after {
92 | left: -16px;
93 | }
94 |
95 | /* The actual content */
96 | .content {
97 | padding: 20px 30px;
98 | background-color: white;
99 | position: relative;
100 | border-radius: 6px;
101 | }
102 |
103 | /* Media queries - Responsive timeline on screens less than 600px wide */
104 | @media screen and (max-width: 600px) {
105 | /* Place the timelime to the left */
106 | .timeline::after {
107 | left: 31px;
108 | }
109 |
110 | /* Full-width containers */
111 | .container {
112 | width: 100%;
113 | padding-left: 70px;
114 | padding-right: 25px;
115 | }
116 |
117 | /* Make sure that all arrows are pointing leftwards */
118 | .container::before {
119 | left: 60px;
120 | border: medium solid white;
121 | border-width: 10px 10px 10px 0;
122 | border-color: transparent white transparent transparent;
123 | }
124 |
125 | /* Make sure all circles are at the same spot */
126 | .left::after,
127 | .right::after {
128 | left: 15px;
129 | }
130 |
131 | /* Make all right containers behave like the left ones */
132 | .right {
133 | left: 0%;
134 | }
135 | }
136 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Welcome to the Remove Commit History exercise!
2 |
3 | This exercise checks your knowledge on removing a commit from the git history of a repository. It is automatically graded via a workflow once you have completed the instructions.
4 |
5 | ## About this exercise
6 |
7 | :warning: A grading script exists under `.github/workflows/grading.yml`. You do not need to use this workflow for any purpose and **altering its contents will affect the repository's ability to assess your exercise and give feedback.**
8 |
9 | :warning: This exercise utilizes [GitHub Actions](https://docs.github.com/en/actions), which is free for public repositories and self-hosted runners, but may incur charges on private repositories. See _[About billing for GitHub Actions]_ to learn more.
10 |
11 | :information_source: The use of GitHub Actions also means that it may take the grading workflow a few seconds and sometimes minutes to run.
12 |
13 | ## Instructions
14 |
15 |
16 |
17 | Please complete the instructions below:
18 |
19 | 1. Create your own copy of this repository by using the [Use this template](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template) button.
20 | 2. Remove all references to the `.env` file which contains sensitive data from the repository.
21 |
22 | You do not need to contact GitHub Support to remove cached commits and complete this exercise.
23 |
24 |
25 |
26 | ## Seeing your result
27 |
28 | Your exercise is graded automatically once you have completed the instructions. To see the result of your exercise, go to the **Actions** tab, and see the most recent run on the **Grading** workflow.
29 |
30 | Below is an example of an incorrect solution and the feedback provided in the **Grading results:**
31 |
32 | 
33 |
34 | See _[Viewing workflow run history]_ if you need assistance.
35 |
36 | ## Troubleshooting
37 |
38 | If you are stuck with a step in the exercise or the grading workflow does not automatically run after you complete the instructions, run the troubleshooter: in the **Actions** tab select the **Grading workflow**, click **Run workflow**, select the appropriate branch, and click the **Run workflow** button.
39 |
40 | 
41 |
42 | The troubleshooter will either display useful information to help you understand what you might have done wrong in your exercise or redirect you to the documentation relevant to your exercise to help you out.
43 |
44 | See _[Running a workflow on GitHub]_ if you need assistance.
45 |
46 | ## Useful resources
47 |
48 | Use these to help you!
49 |
50 | Resources specific to this exercise:
51 |
52 |
53 | - [Removing sensitive data from a repository] - GitHub Docs
54 | - [BFG repo cleaner] - Tool homepage
55 | - [git filter-repo] - Tool repository
56 |
57 | Resources for working with exercises and GitHub Actions in general:
58 |
59 | - [Creating a repository from a template]
60 | - [Viewing workflow run history]
61 | - [Running a workflow on GitHub]
62 | - [About billing for GitHub Actions]
63 | - [GitHub Actions]
64 |
65 |
68 |
69 |
70 | [Removing sensitive data from a repository]: https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository
71 | [BFG repo cleaner]: https://rtyley.github.io/bfg-repo-cleaner/
72 | [git filter-repo]: https://github.com/newren/git-filter-repo/
73 |
74 | [creating a repository from a template]: https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template
75 | [viewing workflow run history]: https://docs.github.com/en/actions/managing-workflow-runs/viewing-workflow-run-history
76 | [running a workflow on github]: https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow#running-a-workflow-on-github
77 | [about billing for github actions]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-actions
78 | [github actions]: https://docs.github.com/en/actions
79 |
--------------------------------------------------------------------------------
/.github/actions/check-history-action/package-lock.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "check-history-action",
3 | "version": "1.0.0",
4 | "lockfileVersion": 1,
5 | "requires": true,
6 | "dependencies": {
7 | "@actions/core": {
8 | "version": "1.4.0",
9 | "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.4.0.tgz",
10 | "integrity": "sha512-CGx2ilGq5i7zSLgiiGUtBCxhRRxibJYU6Fim0Q1Wg2aQL2LTnF27zbqZOrxfvFQ55eSBW0L8uVStgtKMpa0Qlg=="
11 | },
12 | "@actions/github": {
13 | "version": "5.0.0",
14 | "resolved": "https://registry.npmjs.org/@actions/github/-/github-5.0.0.tgz",
15 | "integrity": "sha512-QvE9eAAfEsS+yOOk0cylLBIO/d6WyWIOvsxxzdrPFaud39G6BOkUwScXZn1iBzQzHyu9SBkkLSWlohDWdsasAQ==",
16 | "requires": {
17 | "@actions/http-client": "^1.0.11",
18 | "@octokit/core": "^3.4.0",
19 | "@octokit/plugin-paginate-rest": "^2.13.3",
20 | "@octokit/plugin-rest-endpoint-methods": "^5.1.1"
21 | }
22 | },
23 | "@actions/http-client": {
24 | "version": "1.0.11",
25 | "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-1.0.11.tgz",
26 | "integrity": "sha512-VRYHGQV1rqnROJqdMvGUbY/Kn8vriQe/F9HR2AlYHzmKuM/p3kjNuXhmdBfcVgsvRWTz5C5XW5xvndZrVBuAYg==",
27 | "requires": {
28 | "tunnel": "0.0.6"
29 | }
30 | },
31 | "@octokit/auth-token": {
32 | "version": "2.4.5",
33 | "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.4.5.tgz",
34 | "integrity": "sha512-BpGYsPgJt05M7/L/5FoE1PiAbdxXFZkX/3kDYcsvd1v6UhlnE5e96dTDr0ezX/EFwciQxf3cNV0loipsURU+WA==",
35 | "requires": {
36 | "@octokit/types": "^6.0.3"
37 | }
38 | },
39 | "@octokit/core": {
40 | "version": "3.5.1",
41 | "resolved": "https://registry.npmjs.org/@octokit/core/-/core-3.5.1.tgz",
42 | "integrity": "sha512-omncwpLVxMP+GLpLPgeGJBF6IWJFjXDS5flY5VbppePYX9XehevbDykRH9PdCdvqt9TS5AOTiDide7h0qrkHjw==",
43 | "requires": {
44 | "@octokit/auth-token": "^2.4.4",
45 | "@octokit/graphql": "^4.5.8",
46 | "@octokit/request": "^5.6.0",
47 | "@octokit/request-error": "^2.0.5",
48 | "@octokit/types": "^6.0.3",
49 | "before-after-hook": "^2.2.0",
50 | "universal-user-agent": "^6.0.0"
51 | }
52 | },
53 | "@octokit/endpoint": {
54 | "version": "6.0.12",
55 | "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-6.0.12.tgz",
56 | "integrity": "sha512-lF3puPwkQWGfkMClXb4k/eUT/nZKQfxinRWJrdZaJO85Dqwo/G0yOC434Jr2ojwafWJMYqFGFa5ms4jJUgujdA==",
57 | "requires": {
58 | "@octokit/types": "^6.0.3",
59 | "is-plain-object": "^5.0.0",
60 | "universal-user-agent": "^6.0.0"
61 | }
62 | },
63 | "@octokit/graphql": {
64 | "version": "4.6.4",
65 | "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-4.6.4.tgz",
66 | "integrity": "sha512-SWTdXsVheRmlotWNjKzPOb6Js6tjSqA2a8z9+glDJng0Aqjzti8MEWOtuT8ZSu6wHnci7LZNuarE87+WJBG4vg==",
67 | "requires": {
68 | "@octokit/request": "^5.6.0",
69 | "@octokit/types": "^6.0.3",
70 | "universal-user-agent": "^6.0.0"
71 | }
72 | },
73 | "@octokit/openapi-types": {
74 | "version": "7.3.5",
75 | "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-7.3.5.tgz",
76 | "integrity": "sha512-6bm5lzGDOeSnWHM5W8OZ86RD2KpchynU+/Qlm5hNEFjfLDhwfAY2lSe68YRUEYFGlxSHe0HmakyhvmtWoD3Zog=="
77 | },
78 | "@octokit/plugin-paginate-rest": {
79 | "version": "2.13.5",
80 | "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-2.13.5.tgz",
81 | "integrity": "sha512-3WSAKBLa1RaR/7GG+LQR/tAZ9fp9H9waE9aPXallidyci9oZsfgsLn5M836d3LuDC6Fcym+2idRTBpssHZePVg==",
82 | "requires": {
83 | "@octokit/types": "^6.13.0"
84 | }
85 | },
86 | "@octokit/plugin-rest-endpoint-methods": {
87 | "version": "5.3.4",
88 | "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-5.3.4.tgz",
89 | "integrity": "sha512-2Y2q/FYCsW5tcwIqgnLOgzZXEb3I1VoSQGyHs/Zki/Ufs5H+uT0maPVHatLKw90LQbqK7ON8NpL3Y8IyzG6pNA==",
90 | "requires": {
91 | "@octokit/types": "^6.16.7",
92 | "deprecation": "^2.3.1"
93 | }
94 | },
95 | "@octokit/request": {
96 | "version": "5.6.0",
97 | "resolved": "https://registry.npmjs.org/@octokit/request/-/request-5.6.0.tgz",
98 | "integrity": "sha512-4cPp/N+NqmaGQwbh3vUsYqokQIzt7VjsgTYVXiwpUP2pxd5YiZB2XuTedbb0SPtv9XS7nzAKjAuQxmY8/aZkiA==",
99 | "requires": {
100 | "@octokit/endpoint": "^6.0.1",
101 | "@octokit/request-error": "^2.1.0",
102 | "@octokit/types": "^6.16.1",
103 | "is-plain-object": "^5.0.0",
104 | "node-fetch": "^2.6.1",
105 | "universal-user-agent": "^6.0.0"
106 | }
107 | },
108 | "@octokit/request-error": {
109 | "version": "2.1.0",
110 | "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-2.1.0.tgz",
111 | "integrity": "sha512-1VIvgXxs9WHSjicsRwq8PlR2LR2x6DwsJAaFgzdi0JfJoGSO8mYI/cHJQ+9FbN21aa+DrgNLnwObmyeSC8Rmpg==",
112 | "requires": {
113 | "@octokit/types": "^6.0.3",
114 | "deprecation": "^2.0.0",
115 | "once": "^1.4.0"
116 | }
117 | },
118 | "@octokit/types": {
119 | "version": "6.16.7",
120 | "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.16.7.tgz",
121 | "integrity": "sha512-OuQELiwIKeDySgNID52vm33wDRc2aaX8lKYgAw9Hmw939ITow1HspT8/AH3M3jgGFUMDmHlMNBNEmH7xV7ggXQ==",
122 | "requires": {
123 | "@octokit/openapi-types": "^7.3.5"
124 | }
125 | },
126 | "before-after-hook": {
127 | "version": "2.2.2",
128 | "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.2.tgz",
129 | "integrity": "sha512-3pZEU3NT5BFUo/AD5ERPWOgQOCZITni6iavr5AUw5AUwQjMlI0kzu5btnyD39AF0gUEsDPwJT+oY1ORBJijPjQ=="
130 | },
131 | "deprecation": {
132 | "version": "2.3.1",
133 | "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
134 | "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
135 | },
136 | "is-plain-object": {
137 | "version": "5.0.0",
138 | "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
139 | "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q=="
140 | },
141 | "node-fetch": {
142 | "version": "2.6.1",
143 | "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.1.tgz",
144 | "integrity": "sha512-V4aYg89jEoVRxRb2fJdAg8FHvI7cEyYdVAh94HH0UIK8oJxUfkjlDQN9RbMx+bEjP7+ggMiFRprSti032Oipxw=="
145 | },
146 | "once": {
147 | "version": "1.4.0",
148 | "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
149 | "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
150 | "requires": {
151 | "wrappy": "1"
152 | }
153 | },
154 | "tunnel": {
155 | "version": "0.0.6",
156 | "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
157 | "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="
158 | },
159 | "universal-user-agent": {
160 | "version": "6.0.0",
161 | "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
162 | "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
163 | },
164 | "wrappy": {
165 | "version": "1.0.2",
166 | "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
167 | "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8="
168 | }
169 | }
170 | }
171 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Attribution 4.0 International
2 |
3 | =======================================================================
4 |
5 | Creative Commons Corporation ("Creative Commons") is not a law firm and
6 | does not provide legal services or legal advice. Distribution of
7 | Creative Commons public licenses does not create a lawyer-client or
8 | other relationship. Creative Commons makes its licenses and related
9 | information available on an "as-is" basis. Creative Commons gives no
10 | warranties regarding its licenses, any material licensed under their
11 | terms and conditions, or any related information. Creative Commons
12 | disclaims all liability for damages resulting from their use to the
13 | fullest extent possible.
14 |
15 | Using Creative Commons Public Licenses
16 |
17 | Creative Commons public licenses provide a standard set of terms and
18 | conditions that creators and other rights holders may use to share
19 | original works of authorship and other material subject to copyright
20 | and certain other rights specified in the public license below. The
21 | following considerations are for informational purposes only, are not
22 | exhaustive, and do not form part of our licenses.
23 |
24 | Considerations for licensors: Our public licenses are
25 | intended for use by those authorized to give the public
26 | permission to use material in ways otherwise restricted by
27 | copyright and certain other rights. Our licenses are
28 | irrevocable. Licensors should read and understand the terms
29 | and conditions of the license they choose before applying it.
30 | Licensors should also secure all rights necessary before
31 | applying our licenses so that the public can reuse the
32 | material as expected. Licensors should clearly mark any
33 | material not subject to the license. This includes other CC-
34 | licensed material, or material used under an exception or
35 | limitation to copyright. More considerations for licensors:
36 | wiki.creativecommons.org/Considerations_for_licensors
37 |
38 | Considerations for the public: By using one of our public
39 | licenses, a licensor grants the public permission to use the
40 | licensed material under specified terms and conditions. If
41 | the licensor's permission is not necessary for any reason--for
42 | example, because of any applicable exception or limitation to
43 | copyright--then that use is not regulated by the license. Our
44 | licenses grant only permissions under copyright and certain
45 | other rights that a licensor has authority to grant. Use of
46 | the licensed material may still be restricted for other
47 | reasons, including because others have copyright or other
48 | rights in the material. A licensor may make special requests,
49 | such as asking that all changes be marked or described.
50 | Although not required by our licenses, you are encouraged to
51 | respect those requests where reasonable. More considerations
52 | for the public:
53 | wiki.creativecommons.org/Considerations_for_licensees
54 |
55 | =======================================================================
56 |
57 | Creative Commons Attribution 4.0 International Public License
58 |
59 | By exercising the Licensed Rights (defined below), You accept and agree
60 | to be bound by the terms and conditions of this Creative Commons
61 | Attribution 4.0 International Public License ("Public License"). To the
62 | extent this Public License may be interpreted as a contract, You are
63 | granted the Licensed Rights in consideration of Your acceptance of
64 | these terms and conditions, and the Licensor grants You such rights in
65 | consideration of benefits the Licensor receives from making the
66 | Licensed Material available under these terms and conditions.
67 |
68 |
69 | Section 1 -- Definitions.
70 |
71 | a. Adapted Material means material subject to Copyright and Similar
72 | Rights that is derived from or based upon the Licensed Material
73 | and in which the Licensed Material is translated, altered,
74 | arranged, transformed, or otherwise modified in a manner requiring
75 | permission under the Copyright and Similar Rights held by the
76 | Licensor. For purposes of this Public License, where the Licensed
77 | Material is a musical work, performance, or sound recording,
78 | Adapted Material is always produced where the Licensed Material is
79 | synched in timed relation with a moving image.
80 |
81 | b. Adapter's License means the license You apply to Your Copyright
82 | and Similar Rights in Your contributions to Adapted Material in
83 | accordance with the terms and conditions of this Public License.
84 |
85 | c. Copyright and Similar Rights means copyright and/or similar rights
86 | closely related to copyright including, without limitation,
87 | performance, broadcast, sound recording, and Sui Generis Database
88 | Rights, without regard to how the rights are labeled or
89 | categorized. For purposes of this Public License, the rights
90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar
91 | Rights.
92 |
93 | d. Effective Technological Measures means those measures that, in the
94 | absence of proper authority, may not be circumvented under laws
95 | fulfilling obligations under Article 11 of the WIPO Copyright
96 | Treaty adopted on December 20, 1996, and/or similar international
97 | agreements.
98 |
99 | e. Exceptions and Limitations means fair use, fair dealing, and/or
100 | any other exception or limitation to Copyright and Similar Rights
101 | that applies to Your use of the Licensed Material.
102 |
103 | f. Licensed Material means the artistic or literary work, database,
104 | or other material to which the Licensor applied this Public
105 | License.
106 |
107 | g. Licensed Rights means the rights granted to You subject to the
108 | terms and conditions of this Public License, which are limited to
109 | all Copyright and Similar Rights that apply to Your use of the
110 | Licensed Material and that the Licensor has authority to license.
111 |
112 | h. Licensor means the individual(s) or entity(ies) granting rights
113 | under this Public License.
114 |
115 | i. Share means to provide material to the public by any means or
116 | process that requires permission under the Licensed Rights, such
117 | as reproduction, public display, public performance, distribution,
118 | dissemination, communication, or importation, and to make material
119 | available to the public including in ways that members of the
120 | public may access the material from a place and at a time
121 | individually chosen by them.
122 |
123 | j. Sui Generis Database Rights means rights other than copyright
124 | resulting from Directive 96/9/EC of the European Parliament and of
125 | the Council of 11 March 1996 on the legal protection of databases,
126 | as amended and/or succeeded, as well as other essentially
127 | equivalent rights anywhere in the world.
128 |
129 | k. You means the individual or entity exercising the Licensed Rights
130 | under this Public License. Your has a corresponding meaning.
131 |
132 |
133 | Section 2 -- Scope.
134 |
135 | a. License grant.
136 |
137 | 1. Subject to the terms and conditions of this Public License,
138 | the Licensor hereby grants You a worldwide, royalty-free,
139 | non-sublicensable, non-exclusive, irrevocable license to
140 | exercise the Licensed Rights in the Licensed Material to:
141 |
142 | a. reproduce and Share the Licensed Material, in whole or
143 | in part; and
144 |
145 | b. produce, reproduce, and Share Adapted Material.
146 |
147 | 2. Exceptions and Limitations. For the avoidance of doubt, where
148 | Exceptions and Limitations apply to Your use, this Public
149 | License does not apply, and You do not need to comply with
150 | its terms and conditions.
151 |
152 | 3. Term. The term of this Public License is specified in Section
153 | 6(a).
154 |
155 | 4. Media and formats; technical modifications allowed. The
156 | Licensor authorizes You to exercise the Licensed Rights in
157 | all media and formats whether now known or hereafter created,
158 | and to make technical modifications necessary to do so. The
159 | Licensor waives and/or agrees not to assert any right or
160 | authority to forbid You from making technical modifications
161 | necessary to exercise the Licensed Rights, including
162 | technical modifications necessary to circumvent Effective
163 | Technological Measures. For purposes of this Public License,
164 | simply making modifications authorized by this Section 2(a)
165 | (4) never produces Adapted Material.
166 |
167 | 5. Downstream recipients.
168 |
169 | a. Offer from the Licensor -- Licensed Material. Every
170 | recipient of the Licensed Material automatically
171 | receives an offer from the Licensor to exercise the
172 | Licensed Rights under the terms and conditions of this
173 | Public License.
174 |
175 | b. No downstream restrictions. You may not offer or impose
176 | any additional or different terms or conditions on, or
177 | apply any Effective Technological Measures to, the
178 | Licensed Material if doing so restricts exercise of the
179 | Licensed Rights by any recipient of the Licensed
180 | Material.
181 |
182 | 6. No endorsement. Nothing in this Public License constitutes or
183 | may be construed as permission to assert or imply that You
184 | are, or that Your use of the Licensed Material is, connected
185 | with, or sponsored, endorsed, or granted official status by,
186 | the Licensor or others designated to receive attribution as
187 | provided in Section 3(a)(1)(A)(i).
188 |
189 | b. Other rights.
190 |
191 | 1. Moral rights, such as the right of integrity, are not
192 | licensed under this Public License, nor are publicity,
193 | privacy, and/or other similar personality rights; however, to
194 | the extent possible, the Licensor waives and/or agrees not to
195 | assert any such rights held by the Licensor to the limited
196 | extent necessary to allow You to exercise the Licensed
197 | Rights, but not otherwise.
198 |
199 | 2. Patent and trademark rights are not licensed under this
200 | Public License.
201 |
202 | 3. To the extent possible, the Licensor waives any right to
203 | collect royalties from You for the exercise of the Licensed
204 | Rights, whether directly or through a collecting society
205 | under any voluntary or waivable statutory or compulsory
206 | licensing scheme. In all other cases the Licensor expressly
207 | reserves any right to collect such royalties.
208 |
209 |
210 | Section 3 -- License Conditions.
211 |
212 | Your exercise of the Licensed Rights is expressly made subject to the
213 | following conditions.
214 |
215 | a. Attribution.
216 |
217 | 1. If You Share the Licensed Material (including in modified
218 | form), You must:
219 |
220 | a. retain the following if it is supplied by the Licensor
221 | with the Licensed Material:
222 |
223 | i. identification of the creator(s) of the Licensed
224 | Material and any others designated to receive
225 | attribution, in any reasonable manner requested by
226 | the Licensor (including by pseudonym if
227 | designated);
228 |
229 | ii. a copyright notice;
230 |
231 | iii. a notice that refers to this Public License;
232 |
233 | iv. a notice that refers to the disclaimer of
234 | warranties;
235 |
236 | v. a URI or hyperlink to the Licensed Material to the
237 | extent reasonably practicable;
238 |
239 | b. indicate if You modified the Licensed Material and
240 | retain an indication of any previous modifications; and
241 |
242 | c. indicate the Licensed Material is licensed under this
243 | Public License, and include the text of, or the URI or
244 | hyperlink to, this Public License.
245 |
246 | 2. You may satisfy the conditions in Section 3(a)(1) in any
247 | reasonable manner based on the medium, means, and context in
248 | which You Share the Licensed Material. For example, it may be
249 | reasonable to satisfy the conditions by providing a URI or
250 | hyperlink to a resource that includes the required
251 | information.
252 |
253 | 3. If requested by the Licensor, You must remove any of the
254 | information required by Section 3(a)(1)(A) to the extent
255 | reasonably practicable.
256 |
257 | 4. If You Share Adapted Material You produce, the Adapter's
258 | License You apply must not prevent recipients of the Adapted
259 | Material from complying with this Public License.
260 |
261 |
262 | Section 4 -- Sui Generis Database Rights.
263 |
264 | Where the Licensed Rights include Sui Generis Database Rights that
265 | apply to Your use of the Licensed Material:
266 |
267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right
268 | to extract, reuse, reproduce, and Share all or a substantial
269 | portion of the contents of the database;
270 |
271 | b. if You include all or a substantial portion of the database
272 | contents in a database in which You have Sui Generis Database
273 | Rights, then the database in which You have Sui Generis Database
274 | Rights (but not its individual contents) is Adapted Material; and
275 |
276 | c. You must comply with the conditions in Section 3(a) if You Share
277 | all or a substantial portion of the contents of the database.
278 |
279 | For the avoidance of doubt, this Section 4 supplements and does not
280 | replace Your obligations under this Public License where the Licensed
281 | Rights include other Copyright and Similar Rights.
282 |
283 |
284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability.
285 |
286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
296 |
297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
306 |
307 | c. The disclaimer of warranties and limitation of liability provided
308 | above shall be interpreted in a manner that, to the extent
309 | possible, most closely approximates an absolute disclaimer and
310 | waiver of all liability.
311 |
312 |
313 | Section 6 -- Term and Termination.
314 |
315 | a. This Public License applies for the term of the Copyright and
316 | Similar Rights licensed here. However, if You fail to comply with
317 | this Public License, then Your rights under this Public License
318 | terminate automatically.
319 |
320 | b. Where Your right to use the Licensed Material has terminated under
321 | Section 6(a), it reinstates:
322 |
323 | 1. automatically as of the date the violation is cured, provided
324 | it is cured within 30 days of Your discovery of the
325 | violation; or
326 |
327 | 2. upon express reinstatement by the Licensor.
328 |
329 | For the avoidance of doubt, this Section 6(b) does not affect any
330 | right the Licensor may have to seek remedies for Your violations
331 | of this Public License.
332 |
333 | c. For the avoidance of doubt, the Licensor may also offer the
334 | Licensed Material under separate terms or conditions or stop
335 | distributing the Licensed Material at any time; however, doing so
336 | will not terminate this Public License.
337 |
338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
339 | License.
340 |
341 |
342 | Section 7 -- Other Terms and Conditions.
343 |
344 | a. The Licensor shall not be bound by any additional or different
345 | terms or conditions communicated by You unless expressly agreed.
346 |
347 | b. Any arrangements, understandings, or agreements regarding the
348 | Licensed Material not stated herein are separate from and
349 | independent of the terms and conditions of this Public License.
350 |
351 |
352 | Section 8 -- Interpretation.
353 |
354 | a. For the avoidance of doubt, this Public License does not, and
355 | shall not be interpreted to, reduce, limit, restrict, or impose
356 | conditions on any use of the Licensed Material that could lawfully
357 | be made without permission under this Public License.
358 |
359 | b. To the extent possible, if any provision of this Public License is
360 | deemed unenforceable, it shall be automatically reformed to the
361 | minimum extent necessary to make it enforceable. If the provision
362 | cannot be reformed, it shall be severed from this Public License
363 | without affecting the enforceability of the remaining terms and
364 | conditions.
365 |
366 | c. No term or condition of this Public License will be waived and no
367 | failure to comply consented to unless expressly agreed to by the
368 | Licensor.
369 |
370 | d. Nothing in this Public License constitutes or may be interpreted
371 | as a limitation upon, or waiver of, any privileges and immunities
372 | that apply to the Licensor or You, including from the legal
373 | processes of any jurisdiction or authority.
374 |
375 |
376 | =======================================================================
377 |
378 | Creative Commons is not a party to its public
379 | licenses. Notwithstanding, Creative Commons may elect to apply one of
380 | its public licenses to material it publishes and in those instances
381 | will be considered the “Licensor.” The text of the Creative Commons
382 | public licenses is dedicated to the public domain under the CC0 Public
383 | Domain Dedication. Except for the limited purpose of indicating that
384 | material is shared under a Creative Commons public license or as
385 | otherwise permitted by the Creative Commons policies published at
386 | creativecommons.org/policies, Creative Commons does not authorize the
387 | use of the trademark "Creative Commons" or any other trademark or logo
388 | of Creative Commons without its prior written consent including,
389 | without limitation, in connection with any unauthorized modifications
390 | to any of its public licenses or any other arrangements,
391 | understandings, or agreements concerning use of licensed material. For
392 | the avoidance of doubt, this paragraph does not form part of the
393 | public licenses.
394 |
395 | Creative Commons may be contacted at creativecommons.org.
396 |
--------------------------------------------------------------------------------
/deployment.md:
--------------------------------------------------------------------------------
1 | # Some-Tool
2 |
3 | [](https://travis-ci.com/Some-Tool/deploy)
4 | [](https://Some-Tool.com)
5 | [](https://Some-Tool.com)
6 | [](https://Some-Tool.com)
7 | [](https://Some-Tool.com)
8 |
9 | **Some-Tool.deploy** and **Some-Tool.rollback** are Config-management roles to easily manage the deployment process for scripting applications such as PHP, Python and Ruby. It's an Config-management port for Some-Ochestration.
10 |
11 | - [Some-Tool](#Some-Tool)
12 | - [History](#history)
13 | - [Project name](#project-name)
14 | - [Some-Tool anonymous usage stats](#Some-Tool-anonymous-usage-stats)
15 | - [Who is using Some-Tool?](#who-is-using-Some-Tool)
16 | - [Requirements](#requirements)
17 | - [Installation](#installation)
18 | - [Update](#update)
19 | - [Features](#features)
20 | - [Main workflow](#main-workflow)
21 | - [Role Variables](#role-variables)
22 | - [Deploying](#deploying)
23 | - [Rolling back](#rolling-back)
24 | - [Hooks: Custom tasks](#hooks-custom-tasks)
25 | - [Variables in custom tasks](#variables-in-custom-tasks)
26 | - [Pruning old releases](#pruning-old-releases)
27 | - [Example Playbook](#example-playbook)
28 | - [Sample projects](#sample-projects)
29 | - [They're talking about us](#theyre-talking-about-us)
30 | - [License](#license)
31 | - [Other resources](#other-resources)
32 |
33 | ## History
34 |
35 | [Some-Ochestration](http://Some-Ochestrationrb.com/) is a remote server automation tool and it's currently in Version 3. [Version 2.0](https://github.com/Some-Ochestration/Some-Ochestration/tree/legacy-v2) was originally thought in order to deploy RoR applications. With additional plugins, you were able to deploy non Rails applications such as PHP and Python, with different deployment strategies, stages and much more. I loved Some-Ochestration v2. I have used it a lot. I developed a plugin for it.
36 |
37 | Some-Ochestration 2 was a great tool and it still works really well. However, it is not maintained anymore since the original team is working in v3. This new version does not have the same set of features so it is less powerful and flexible. Besides that, other new tools are becoming easier to use in order to deploy applications, such as Config-management.
38 |
39 | So, I have decided to stop using Some-Ochestration because v2 is not maintained, v3 does not have enough features, and I can do everything Some-Ochestration was doing with Config-management. If you are looking for alternatives, check Fabric or Chef Solo.
40 |
41 | ## Project name
42 |
43 | Some-Tool comes from Config-management + Some-Ochestration, easy, isn't it?
44 |
45 | ## Some-Tool anonymous usage stats
46 |
47 | There is an optional step in Some-Tool that sends a HTTP request to our servers. Unfortunately, the metrics we can get from Config-management Galaxy are limited so this is one of the few ways we have to measure how many active users we really have.
48 |
49 | We only use this data for usage statistics but anyway, if you are not comfortable with this, you can disable this extra step by setting `Some-Tool_allow_anonymous_stats` to false in your playbooks.
50 |
51 | ## Who is using Some-Tool?
52 |
53 | Is Some-Tool ready to be used? Here are some companies currently using it:
54 |
55 | - [ABA English](http://www.abaenglish.com/)
56 | - [Another Place Productions](http://www.anotherplaceproductions.com)
57 | - [Aptvision](https://www.aptvision.com)
58 | - [ARTACK WebLab](https://www.artack.ch)
59 | - [Atrápalo](http://www.atrapalo.com)
60 | - [Beroomers](https://www.beroomers.com)
61 | - [CMP Group](http://www.teamcmp.com)
62 | - [Cabissimo](https://www.cabissimo.com)
63 | - [Camel Secure](https://camelsecure.com)
64 | - [Cherry Hill](https://chillco.com)
65 | - [Claranet France](http://www.claranet.fr/)
66 | - [Clearpoint](http://www.clearpoint.co.nz)
67 | - [Clever Age](https://www.clever-age.com)
68 | - [CridaDemocracia](https://cridademocracia.org)
69 | - [Cycloid](http://www.cycloid.io)
70 | - [Daemonit](https://daemonit.com)
71 | - [Deliverea](https://www.deliverea.com/)
72 | - [DevOps Barcelona Conference](https://devops.barcelona/)
73 | - [EnAlquiler](http://www.enalquiler.com/)
74 | - [Euromillions.com](http://euromillions.com/)
75 | - [Finizens](https://finizens.com/)
76 | - [FloraQueen](https://www.floraqueen.com/)
77 | - [Fluxus](http://www.fluxus.io/)
78 | - [Geocalia](https://geocalia.com/)
79 | - [Gstock](http://www.g-stock.es)
80 | - [HackSoft](https://hacksoft.io/)
81 | - [HackConf](https://hackconf.bg/en/)
82 | - [Hexanet](https://www.hexanet.fr)
83 | - [HiringThing](https://www.hiringthing.com/)
84 | - [Holaluz](https://www.holaluz.com)
85 | - [Hosting4devs](https://hosting4devs.com)
86 | - [Jolicode](http://jolicode.com/)
87 | - [Kidfund](http://link.kidfund.us/github "Kidfund")
88 | - [Lumao SAS](https://lumao.eu)
89 | - [mailXpert](https://www.mailxpert.ch)
90 | - [MEDIA.figaro](http://media.figaro.fr)
91 | - [Moss](https://moss.sh)
92 | - [Nice&Crazy](http://www.niceandcrazy.com)
93 | - [Nodo Ámbar](http://www.nodoambar.com/)
94 | - [Oferplan](http://oferplan.com/)
95 | - [Ofertix](http://www.ofertix.com)
96 | - [Òmnium Cultural](https://www.omnium.cat)
97 | - [OpsWay Software Factory](http://opsway.com)
98 | - [Parkimeter](https://parkimeter.com)
99 | - [PHP Barcelona Conference](https://php.barcelona/)
100 | - [Scoutim](https://scoutim.com)
101 | - [Socialnk](https://socialnk.com/)
102 | - [Spotahome](https://www.spotahome.com)
103 | - [Suntransfers](http://www.suntransfers.com)
104 | - [TechPump](http://www.techpump.com/)
105 | - [Tienda Online VirginMobile](https://cambiate.virginmobile.cl)
106 | - [The Cocktail](https://the-cocktail.com/)
107 | - [Timehook](https://timehook.io)
108 | - [TMTFactory](https://tmtfactory.com)
109 | - [UNICEF Comité Español](https://www.unicef.es)
110 | - [Ulabox](https://www.ulabox.com)
111 | - [Uvinum](http://www.uvinum.com)
112 | - [VirginMobile Chile](https://empresas.virginmobile.cl)
113 | - [Wavecontrol](http://monitoring.wavecontrol.com/ca/public/demo/)
114 | - [WAVE Meditation](https://wavemeditation.com/)
115 | - [Yubl](https://yubl.me/)
116 |
117 | If you are also using it, please let us know via a PR to this document.
118 |
119 | ## Requirements
120 |
121 | In order to deploy your apps with Some-Tool, you will need:
122 |
123 | - Config-management in your deployer machine
124 | - `rsync` on the target machine if you are using either the `rsync`, `rsync_direct`, or `git` deployment strategy or if you are using `Some-Tool_current_via = rsync`
125 |
126 | ## Installation
127 |
128 | Some-Tool is an Config-management role distributed globally using [Config-management Galaxy](https://galaxy.Config-management.com/). In order to install Some-Tool role you can use the following command.
129 |
130 | ```
131 | $ Config-management-galaxy install Some-Tool.deploy Some-Tool.rollback
132 | ```
133 |
134 | ## Update
135 |
136 | If you want to update the role, you need to pass **--force** parameter when installing. Please, check the following command:
137 |
138 | ```
139 | $ Config-management-galaxy install --force Some-Tool.deploy Some-Tool.rollback
140 | ```
141 |
142 | ## Features
143 |
144 | - Rollback in seconds (with Some-Tool.rollback role)
145 | - Customize your deployment with hooks before and after critical steps
146 | - Save disk space keeping a maximum fixed releases in your hosts
147 | - Choose between SCP, RSYNC, GIT, SVN, HG, HTTP Download or S3 GET deployment strategies (optional unarchive step included)
148 |
149 | ## Main workflow
150 |
151 | Some-Tool deploys applications following the Some-Ochestration flow.
152 |
153 | - Setup phase: Creates the folder structure to hold your releases
154 | - Code update phase: Puts the new release into your hosts
155 | - Symlink phase: After deploying the new release into your hosts, this step changes the `current` softlink to new the release
156 | - Cleanup phase: Removes any old version based in the `Some-Tool_keep_releases` parameter (see "Role Variables")
157 |
158 | 
159 |
160 | ## Role Variables
161 |
162 | ```yaml
163 | vars:
164 | Some-Tool_deploy_from: "{{ playbook_dir }}/" # Where my local project is (relative or absolute path)
165 | Some-Tool_deploy_to: "/var/www/my-app" # Base path to deploy to.
166 | Some-Tool_version_dir: "releases" # Releases folder name
167 | Some-Tool_current_dir: "current" # Softlink name. You should rarely changed it.
168 | Some-Tool_current_via: "symlink" # Deployment strategy who code should be deployed to current path. Options are symlink or rsync
169 | Some-Tool_keep_releases: 0 # Releases to keep after a new deployment. See "Pruning old releases".
170 |
171 | # Arrays of directories and files to be shared.
172 | # The following arrays of directories and files will be symlinked to the current release directory after the 'update-code' step and its callbacks
173 | # Notes:
174 | # * Paths are relative to the /shared directory (no starting /)
175 | # * If your items are in a subdirectory, write the entire path to each shared directory
176 | #
177 | # Example:
178 | # Some-Tool_shared_paths:
179 | # - path/to/first-dir
180 | # - path/next-dir
181 | # Some-Tool_shared_files:
182 | # - my-file.txt
183 | # - path/to/file.txt
184 | Some-Tool_shared_paths: []
185 | Some-Tool_shared_files: []
186 |
187 | # Shared paths and basedir shared files creation.
188 | # By default the shared paths directories and base directories for shared files are created automatically if not exists. But in some scenarios those paths could be symlinks to another directories in the filesystem, and the deployment process would fails. With these variables you can disable the involved tasks. If you have two or three shared paths, and don't need creation only for some of them, you always could disable the automatic creation and add a custom task in a hook.
189 | Some-Tool_ensure_shared_paths_exist: yes
190 | Some-Tool_ensure_basedirs_shared_files_exist: yes
191 |
192 | # Deployment strategy - method used to deliver code. Options are copy, download, git, rsync, rsync_direct, svn, or s3.
193 | Some-Tool_deploy_via: rsync
194 | # Copy, download and s3 have an optional step to unarchive the downloaded file which can be used by adding _unarchive.
195 | # The rsync_direct strategy omits a file copy on the target offering a slight speed increase if you are deploying to shared hosts, are experiancing bad file-performance, or serve static assets from the same host you deploy your app to and rsync many files.
196 | # You can check all the options inside tasks/update-code folder!
197 |
198 | Some-Tool_allow_anonymous_stats: yes
199 |
200 | # Variables used in the rsync/rsync_direct deployment strategy
201 | Some-Tool_rsync_extra_params: "" # Extra parameters to use when deploying with rsync in a single string. Although Config-management allows an array this can cause problems if we try to add multiple --include args as it was reported in https://github.com/Some-Tool/deploy/commit/e98942dc969d4e620313f00f003a7ea2eab67e86
202 | Some-Tool_rsync_set_remote_user: yes # See [Config-management synchronize module](http://docs.Config-management.com/Config-management/synchronize_module.html). Options are yes, no.
203 | Some-Tool_rsync_path: "" # See [Config-management synchronize module](http://docs.Config-management.com/Config-management/synchronize_module.html). By default is "sudo rsync", it can be overwriten with (example): "sudo -u user rsync".
204 | Some-Tool_rsync_use_ssh_args: no # See [Config-management synchronize module](http://docs.Config-management.com/Config-management/synchronize_module.html). If set yes, use the ssh_args specified in Config-management.cfg.
205 |
206 | # Variables used in the Git deployment strategy
207 | Some-Tool_git_repo: git@github.com:USERNAME/REPO.git # Location of the git repository
208 | Some-Tool_git_branch: master # What version of the repository to check out. This can be the full 40-character SHA-1 hash, the literal string HEAD, a branch name, or a tag name
209 | Some-Tool_git_repo_tree: "" # If specified the subtree of the repository to deploy
210 | Some-Tool_git_identity_key_path: "" # If specified this file is copied over and used as the identity key for the git commands, path is relative to the playbook in which it is used
211 | Some-Tool_git_identity_key_remote_path: "" # If specified this file on the remote server is used as the identity key for the git commands, remote path is absolute
212 | # Optional variables, omitted by default
213 | Some-Tool_git_refspec: ADDITIONAL_GIT_REFSPEC # Additional refspec to be used by the 'git' module. Uses the same syntax as the 'git fetch' command.
214 | Some-Tool_git_ssh_opts: "-o StrictHostKeyChecking=no" # Additional ssh options to be used in Git
215 | Some-Tool_git_depth: 1 # Additional history truncated to the specified number or revisions
216 | Some-Tool_git_executable: /opt/local/bin/git # Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used.
217 |
218 | # Variables used in the SVN deployment strategy
219 | # Please note there was a bug in the subversion module in Config-management 1.8.x series (https://github.com/Config-management/Config-management-modules-core/issues/370) so it is only supported from Config-management 1.9
220 | Some-Tool_svn_repo: https://svn.company.com/project # Location of the svn repository
221 | Some-Tool_svn_branch: trunk # What branch from the repository to check out.
222 | Some-Tool_svn_revision: HEAD # What revision from the repository to check out.
223 | Some-Tool_svn_username: user # SVN authentication username
224 | Some-Tool_svn_password: Pa$$word # SVN authentication password
225 | Some-Tool_svn_environment: {} # Dict with environment variables for svn tasks (https://docs.Config-management.com/Config-management/playbooks_environment.html)
226 |
227 | # Variables used in the HG deployment strategy
228 | Some-Tool_hg_repo: https://USERNAME@bitbucket.org/USERNAME/REPO # Location of the hg repo
229 | Some-Tool_hg_branch: default # Any branch identifier that works with hg -r, so named branch, bookmark, commit hash...
230 |
231 | # Variables used in the download deployment strategy
232 | Some-Tool_get_url: https://github.com/someproject/somearchive.tar.gz
233 | Some-Tool_download_force_basic_auth: false # no default as this is only supported from Config-management 2.0
234 | Some-Tool_download_headers: "" # no default as this is only supported from Config-management 2.0
235 |
236 | # Variables used in the S3 deployment strategy
237 | Some-Tool_s3_bucket: s3bucket
238 | Some-Tool_s3_object: s3object.tgz # Add the _unarchive suffix to the Some-Tool_deploy_via if your object is a package (ie: s3_unarchive)
239 | Some-Tool_s3_region: eu-west-1
240 | Some-Tool_s3_rgw: false # must be Config-management >= 2.2. use Ceph RGW for S3 compatible cloud providers
241 | Some-Tool_s3_url: http://rgw.example.com # when use Ceph RGW, set url
242 | # Optional variables, omitted by default
243 | Some-Tool_s3_aws_access_key: YOUR_AWS_ACCESS_KEY
244 | Some-Tool_s3_aws_secret_key: YOUR_AWS_SECRET_KEY
245 | Some-Tool_s3_ignore_nonexistent_bucket: false
246 |
247 | # Variables used in the GCS deployment strategy
248 | Some-Tool_gcs_bucket: gcsbucket
249 | Some-Tool_gcs_object: gcsobject.tgz # Add the _unarchive suffix to the Some-Tool_deploy_via if your object is a package (ie: s3_unarchive)
250 | Some-Tool_gcs_region: eu-west-1 # https://cloud.google.com/storage/docs/bucket-locations
251 | # Optional variables, omitted by default
252 | Some-Tool_gcs_access_key: YOUR_GCS_ACCESS_KEY # navigate to Cloud console > Storage > Settings > Interoperability
253 | Some-Tool_gcs_secret_key: YOUR_GCS_SECRET_KEY
254 |
255 | # Hooks: custom tasks if you need them
256 | Some-Tool_before_setup_tasks_file: "{{ playbook_dir }}//my-before-setup-tasks.yml"
257 | Some-Tool_after_setup_tasks_file: "{{ playbook_dir }}//my-after-setup-tasks.yml"
258 | Some-Tool_before_update_code_tasks_file: "{{ playbook_dir }}//my-before-update-code-tasks.yml"
259 | Some-Tool_after_update_code_tasks_file: "{{ playbook_dir }}//my-after-update-code-tasks.yml"
260 | Some-Tool_before_symlink_shared_tasks_file: "{{ playbook_dir }}//my-before-symlink-shared-tasks.yml"
261 | Some-Tool_after_symlink_shared_tasks_file: "{{ playbook_dir }}//my-after-symlink-shared-tasks.yml"
262 | Some-Tool_before_symlink_tasks_file: "{{ playbook_dir }}//my-before-symlink-tasks.yml"
263 | Some-Tool_after_symlink_tasks_file: "{{ playbook_dir }}//my-after-symlink-tasks.yml"
264 | Some-Tool_before_cleanup_tasks_file: "{{ playbook_dir }}//my-before-cleanup-tasks.yml"
265 | Some-Tool_after_cleanup_tasks_file: "{{ playbook_dir }}//my-after-cleanup-tasks.yml"
266 | ```
267 |
268 | `{{ playbook_dir }}` is an Config-management variable that holds the path to the current playbook.
269 |
270 | ## Deploying
271 |
272 | In order to deploy with Some-Tool, you need to perform some steps:
273 |
274 | - Create a new `hosts` file. Check [Config-management inventory documentation](http://docs.Config-management.com/intro_inventory.html) if you need help. This file will identify all the hosts where to deploy to. For multistage environments check [Multistage environments](#multistage-environment-devel-preprod-prod-etc).
275 | - Create a new playbook for deploying your app, for example, `deploy.yml`
276 | - Set up role variables (see [Role Variables](#role-variables))
277 | - Include the `Some-Tool.deploy` role as part of a play
278 | - Run the deployment playbook
279 |
280 | `Config-management-playbook -i hosts deploy.yml`
281 |
282 | If everything has been set up properly, this command will create the following approximate directory structure on your server. Check how the hosts folder structure would look like after one, two and three deployments.
283 |
284 | ```
285 | -- /var/www/my-app.com
286 | |-- current -> /var/www/my-app.com/releases/20100509145325
287 | |-- releases
288 | | |-- 20100509145325
289 | |-- shared
290 | ```
291 |
292 | ```
293 | -- /var/www/my-app.com
294 | |-- current -> /var/www/my-app.com/releases/20100509150741
295 | |-- releases
296 | | |-- 20100509150741
297 | | |-- 20100509145325
298 | |-- shared
299 | ```
300 |
301 | ```
302 | -- /var/www/my-app.com
303 | |-- current -> /var/www/my-app.com/releases/20100512131539
304 | |-- releases
305 | | |-- 20100512131539
306 | | |-- 20100509150741
307 | | |-- 20100509145325
308 | |-- shared
309 | ```
310 |
311 | ### Serial deployments
312 |
313 | To prevent different timestamps when deploying to several servers using the [`serial`](http://docs.Config-management.com/playbooks_delegation.html#rolling-update-batch-size) option, you should set the `Some-Tool_release_version` variable.
314 |
315 | `` Config-management-playbook -i hosts -e "Some-Tool_release_version=`date -u +%Y%m%d%H%M%SZ`" deploy.yml ``
316 |
317 | ## Rolling back
318 |
319 | In order to rollback with Some-Tool, you need to set up the deployment and run the rollback playbook.
320 |
321 | `Config-management-playbook -i hosts rollback.yml`
322 |
323 | If you try to rollback with zero or one releases deployed, an error will be raised and no actions performed.
324 |
325 | Variables you can tune in rollback role are less than in deploy one:
326 |
327 | ```yaml
328 | vars:
329 | Some-Tool_deploy_to: "/var/www/my-app" # Base path to deploy to.
330 | Some-Tool_version_dir: "releases" # Releases folder name
331 | Some-Tool_current_dir: "current" # Softlink name. You should rarely changed it.
332 | Some-Tool_rollback_to_release: "" # If specified, the application will be rolled back to this release version; previous release otherwise.
333 | Some-Tool_remove_rolled_back: yes # You can change this setting in order to keep the rolled back release in the server for later inspection
334 | Some-Tool_allow_anonymous_stats: yes
335 |
336 | # Hooks: custom tasks if you need them
337 | Some-Tool_rollback_before_setup_tasks_file: "{{ playbook_dir }}//my-rollback-before-setup-tasks.yml"
338 | Some-Tool_rollback_after_setup_tasks_file: "{{ playbook_dir }}//my-rollback-after-setup-tasks.yml"
339 | Some-Tool_rollback_before_symlink_tasks_file: "{{ playbook_dir }}//my-rollback-before-symlink-tasks.yml"
340 | Some-Tool_rollback_after_symlink_tasks_file: "{{ playbook_dir }}//my-rollback-after-symlink-tasks.yml"
341 | Some-Tool_rollback_before_cleanup_tasks_file: "{{ playbook_dir }}//my-rollback-before-cleanup-tasks.yml"
342 | Some-Tool_rollback_after_cleanup_tasks_file: "{{ playbook_dir }}//my-rollback-after-cleanup-tasks.yml"
343 | ```
344 |
345 | ## Multistage environment (devel, preprod, prod, etc.)
346 |
347 | If you want to deploy to different environments such as devel, preprod and prod, it's recommended to create different hosts files. When done, you can specify a different host file when running the deployment playbook using the **-i** parameter. On every host file, you can specify different users, password, connection parameters, etc.
348 |
349 | `Config-management-playbook -i hosts_devel deploy.yml`
350 |
351 | `Config-management-playbook -i hosts_preprod deploy.yml`
352 |
353 | `Config-management-playbook -i hosts_prod deploy.yml`
354 |
355 | ## Hooks: Custom tasks
356 |
357 | You will typically need to reload your webserver after the `Symlink` step, or download your dependencies before `Code update` or even do it in production before the `Symlink`. So, in order to perform your custom tasks you have some hooks that Some-Tool will execute before and after each of the main 3 steps. **This is the main benefit against other similar deployment roles.**
358 |
359 | ```
360 | -- /my-local-machine/my-app.com
361 | |-- hosts
362 | |-- deploy.yml
363 | |-- my-custom-tasks
364 | | |-- before-code-update.yml
365 | | |-- after-code-update.yml
366 | | |-- before-symlink.yml
367 | | |-- after-symlink.yml
368 | | |-- before-cleanup.yml
369 | | |-- after-cleanup.yml
370 | ```
371 |
372 | For example, in order to restart apache after `Symlink` step, we'll add in the `after-symlink.yml`
373 |
374 | ```
375 | - name: Restart Apache
376 | service: name=httpd state=reloaded
377 | ```
378 |
379 | - **Q: Where would you add sending email notification after a deployment?**
380 | - **Q: (for PHP and Symfony developers) Where would you clean the cache?**
381 |
382 | You can specify a custom tasks file for before and after every step using `Some-Tool_before_*_tasks_file` and `Some-Tool_after_*_tasks_file` role variables. See "Role Variables" for more information.
383 |
384 | ## Variables in custom tasks
385 |
386 | When writing your custom tasks files you may need some variables that Some-Tool makes available to you:
387 |
388 | - `{{ Some-Tool_release_path.stdout }}`: Path to current deployment release (probably the one you are going to use the most)
389 | - `{{ Some-Tool_releases_path }}`: Path to releases folder
390 | - `{{ Some-Tool_shared_path }}`: Path to shared folder (where common releases assets can be stored)
391 | - `{{ Some-Tool_release_version }}`: Relative directory name for the release (by default equals to the current timestamp in UTC timezone)
392 |
393 | ## Pruning old releases
394 |
395 | In continuous delivery environments, you will possibly have a high number of releases in production. Maybe you have tons of space and you don't mind, but it's common practice to keep just a custom number of releases.
396 |
397 | After the deployment, if you want to remove old releases just set the `Some-Tool_keep_releases` variable to the total number of releases you want to keep.
398 |
399 | Let's see three deployments with an `Some-Tool_keep_releases: 2` configuration:
400 |
401 | ```
402 | -- /var/www/my-app.com
403 | |-- current -> /var/www/my-app.com/releases/20100509145325
404 | |-- releases
405 | | |-- 20100509145325
406 | |-- shared
407 | ```
408 |
409 | ```
410 | -- /var/www/my-app.com
411 | |-- current -> /var/www/my-app.com/releases/20100509150741
412 | |-- releases
413 | | |-- 20100509150741
414 | | |-- 20100509145325
415 | |-- shared
416 | ```
417 |
418 | ```
419 | -- /var/www/my-app.com
420 | |-- current -> /var/www/my-app.com/releases/20100512131539
421 | |-- releases
422 | | |-- 20100512131539
423 | | |-- 20100509150741
424 | |-- shared
425 | ```
426 |
427 | See how the release `20100509145325` has been removed.
428 |
429 | ## Example Playbook
430 |
431 | In the folder, `example` you can check an example project that shows how to deploy a small application with Some-Tool.
432 |
433 | In order to run it, you will need to have Vagrant and the Some-Tool roles installed. Please check https://www.vagrantup.com for more information about Vagrant and our Installation section.
434 |
435 | ```
436 | $ cd example/my-playbook
437 | $ vagrant up
438 | $ Config-management-playbook -i hosts deploy.yml
439 | ```
440 |
441 | And after running these commands, the index.html located in the `my-app` folder will be deployed to both vagrant boxes
442 |
443 | In order to test the rollback playbook, you will need to run deploy.yml at least twice (so that there is something to rollback to). And once this is done, you only need to run
444 |
445 | ```
446 | $ Config-management-playbook -i hosts rollback.yml
447 | ```
448 |
449 | You can check more advanced examples inside the test folder which are run against Travis-CI
450 |
451 | ## Sample projects
452 |
453 | We have added Some-Tool support for other projects we are working on.
454 |
455 | - LastWishes: Domain-Driven Design PHP Sample App: https://github.com/dddinphp/last-wishes
456 |
457 | As an example, see the execution log of the LastWishes deployment:
458 |
459 | ```
460 | PLAY [Deploy last wishes app to my server] ************************************
461 |
462 | GATHERING FACTS ***************************************************************
463 | ok: [quepimquepam.com]
464 |
465 | TASK: [Some-Tool.deploy | Ensure deployment base path exists] ***
466 | ok: [quepimquepam.com]
467 |
468 | TASK: [Some-Tool.deploy | Ensure releases folder exists] ***
469 | ok: [quepimquepam.com]
470 |
471 | TASK: [Some-Tool.deploy | Ensure shared elements folder exists] ***
472 | ok: [quepimquepam.com]
473 |
474 | TASK: [Some-Tool.deploy | Get release timestamp] ***********
475 | changed: [quepimquepam.com]
476 |
477 | TASK: [Some-Tool.deploy | Get release path] ****************
478 | changed: [quepimquepam.com]
479 |
480 | TASK: [Some-Tool.deploy | Get releases path] ***************
481 | changed: [quepimquepam.com]
482 |
483 | TASK: [Some-Tool.deploy | Get shared path (in rsync case)] ***
484 | changed: [quepimquepam.com]
485 |
486 | TASK: [Some-Tool.deploy | Rsync application files to remote shared copy (in rsync case)] ***
487 | changed: [quepimquepam.com -> 127.0.0.1]
488 |
489 | TASK: [Some-Tool.deploy | Deploy existing code to servers] ***
490 | changed: [quepimquepam.com]
491 |
492 | TASK: [Some-Tool.deploy | Deploy existing code to remote servers] ***
493 | skipping: [quepimquepam.com]
494 |
495 | TASK: [Some-Tool.deploy | Update remote repository] ********
496 | skipping: [quepimquepam.com]
497 |
498 | TASK: [Some-Tool.deploy | Export a copy of the repo] *******
499 | skipping: [quepimquepam.com]
500 |
501 | TASK: [Some-Tool.deploy | Deploy code from to servers] *****
502 | skipping: [quepimquepam.com]
503 |
504 | TASK: [Some-Tool.deploy | Copy release version into REVISION file] ***
505 | changed: [quepimquepam.com]
506 |
507 | TASK: [Some-Tool.deploy | Touches up the release code] *****
508 | changed: [quepimquepam.com]
509 |
510 | TASK: [Some-Tool.deploy | Change softlink to new release] ***
511 | changed: [quepimquepam.com]
512 |
513 | TASK: [Some-Tool.deploy | Reload Apache] *******************
514 | changed: [quepimquepam.com]
515 |
516 | TASK: [Some-Tool.deploy | Clean up releases] ***************
517 | skipping: [quepimquepam.com]
518 |
519 | PLAY RECAP ********************************************************************
520 | quepimquepam.com : ok=14 changed=10 unreachable=0 failed=0
521 | ```
522 |
523 | ## They're talking about us
524 |
525 | - [Pablo Godel - Deploying Symfony - Symfony Cat 2016](https://youtu.be/K2bBhrkmpSg?t=26m)
526 | - [https://www.artansoft.com/2016/05/deploy-de-proyectos-php-Some-Tool/](https://www.artansoft.com/2016/05/deploy-de-proyectos-php-Some-Tool/)
527 | - [http://alexmoreno.net/Some-Tool-deploying-drupal-Config-management](http://alexmoreno.net/Some-Tool-deploying-drupal-Config-management)
528 | - [http://www.ricardclau.com/2015/10/deploying-php-applications-with-Some-Tool/](http://www.ricardclau.com/2015/10/deploying-php-applications-with-Some-Tool/)
529 | - [http://es.slideshare.net/OrestesCA/Config-management-intro-Config-management-barcelona-user-group-june-2015](http://es.slideshare.net/OrestesCA/Config-management-intro-Config-management-barcelona-user-group-june-2015)
530 | - [http://carlosbuenosvinos.com/deploying-symfony-and-php-apps-with-Some-Tool/](http://carlosbuenosvinos.com/deploying-symfony-and-php-apps-with-Some-Tool/)
531 | - [https://www.youtube.com/watch?v=CPz5zPzzMZE](https://www.youtube.com/watch?v=CPz5zPzzMZE)
532 | - [https://github.com/cbrunnkvist/Some-Tool-symfony-deploy](https://github.com/cbrunnkvist/Some-Tool-symfony-deploy)
533 | - [https://www.reddit.com/r/Config-management/comments/2ezzz5/rapid_rollback_with_Config-management/](https://www.reddit.com/r/Config-management/comments/2ezzz5/rapid_rollback_with_Config-management/)
534 | - [Cookiecutting Config-management for Django](https://hacksoft.io/blog/cookiecutting-django-Config-management/)
535 | - [Deploying PHP applications with Config-management, Config-management Vault and Some-Tool](https://www.oliverdavies.uk/talks/deploying-php-Config-management-Some-Tool)
536 |
537 | ## License
538 |
539 | MIT
540 |
541 | ## Other resources
542 |
543 | - [Thoughts on deploying with Config-management](http://www.future500.nl/articles/2014/07/thoughts-on-deploying-with-Config-management/)
544 | - [Docker image](https://hub.docker.com/r/lavoweb/Some-Tool/)
545 |
--------------------------------------------------------------------------------