-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
122 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| <!DOCTYPE html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="UTF-8"> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> | ||
| <title>SERVICES.YML - A simple file format for documenting services used by Rails apps</title> | ||
| <script src="https://cdn.tailwindcss.com"></script> | ||
| <style> | ||
| body { | ||
| background-color: #002082; | ||
| color: #CED8F7; | ||
| font-family: 'Courier New', Courier, monospace; | ||
| } | ||
| h1, h2, h3, h4, h5, h6 { | ||
| color: #FFFFFF; | ||
| } | ||
| </style> | ||
| </head> | ||
| <body class="flex items-center justify-center min-h-screen my-8" style="background-image: url('data:image/svg+xml;utf8,<svg xmlns=%22http://www.w3.org/2000/svg%22 width=%22100%25%22 height=%22100%25%22 style=%22background-color: %23002082;%22><pattern id=%22smallGrid%22 width=%2210%22 height=%2210%22 patternUnits=%22userSpaceOnUse%22><path d=%22M 10 0 L 0 0 0 10%22 fill=%22none%22 stroke=%22%23446cb3%22 stroke-width=%220.5%22/></pattern><pattern id=%22largeGrid%22 width=%2250%22 height=%2250%22 patternUnits=%22userSpaceOnUse%22><rect width=%2250%22 height=%2250%22 fill=%22url(%23smallGrid)%22/><path d=%22M 50 0 L 0 0 0 50%22 fill=%22none%22 stroke=%22%234466cc%22 stroke-width=%221.5%22/></pattern><rect width=%22100%25%22 height=%22100%25%22 fill=%22url(%23largeGrid)%22/></svg>');"> | ||
|
|
||
| <div class=" p-8 rounded-lg max-w-4xl w-full mx-4"> | ||
| <header class="p-8 rounded-lg -mt-10 sm:mt-0"> | ||
| <h1 class="text-4xl sm:text-5xl md:text-6xl font-bold mb-1 mt-[2px]">SERVICES.YML</h1> | ||
| <p class="text-lg">A simple file format for documenting services used by Rails apps</p> | ||
| </header> | ||
|
|
||
| <section class="bg-[#4A6DE5] mb-8 bg-opacity-75 p-8 rounded-lg"> | ||
| <h2 class="text-3xl font-semibold mb-4">The problem</h2> | ||
| <p class="mb-4 last:mb-0 -mt-2"> | ||
| Rails apps often use a dozen or more third-party services and it can quickly become difficult to remember which services are used by the app, especially when working with many apps. | ||
| </p> | ||
| </section> | ||
|
|
||
| <section class="bg-[#4A6DE5] mb-8 bg-opacity-75 p-8 rounded-lg"> | ||
| <h2 class="text-3xl font-semibold mb-4">The solution</h2> | ||
| <p class="mb-4 -mt-2"> | ||
| We can fix this by adding a list of services to our app. | ||
| </p> | ||
| <p class="mb-4"> | ||
| The list should: | ||
| </p> | ||
| <ul class="list-disc list-inside mb-4 last:mb-0"> | ||
| <li>Be named <code class="bg-gray-800 p-1 rounded">SERVICES.YML</code></li> | ||
| <li>Be stored in the root of the app</li> | ||
| <li>Use the YAML format when possible</li> | ||
| <li>Use single words to describe service types</li> | ||
| <li>Start with the hosting provider</li> | ||
| <li>Place all other service types in alphabetical order</li> | ||
| <li>Be updated when you change service providers</li> | ||
| </ul> | ||
| </section> | ||
|
|
||
| <section class="bg-[#4A6DE5] mb-8 bg-opacity-75 p-8 rounded-lg"> | ||
| <h2 class="text-3xl font-semibold mb-4">Example</h2> | ||
| <pre class="bg-gray-800 p-4 rounded text-white"> | ||
| hosting: digitalocean | ||
| advertising: google | ||
| email: | ||
| transactional: postmark | ||
| spam: akismet | ||
| mapping: | ||
| geocoding: google | ||
| maps: apple | ||
| monitoring: sentry | ||
| storage: | ||
| amazon: | ||
| - cloudfront | ||
| - s3</pre> | ||
| </section> | ||
|
|
||
| <section class="bg-[#4A6DE5] mb-8 bg-opacity-75 p-8 rounded-lg"> | ||
| <h2 class="text-3xl font-semibold mb-4">FAQ</h2> | ||
|
|
||
| <div class="mb-4"> | ||
| <h3 class="text-2xl font-semibold mb-2">Why not just use ENV variables?</h3> | ||
| <p class="mb-4"> | ||
| ENV variables are used to store app secrets and other configuration settings. We want a short list that we can read and understand in a glance. | ||
| </p> | ||
| </div> | ||
|
|
||
| <div class="mb-4"> | ||
| <h3 class="text-2xl font-semibold mb-2">Why not just use a Gemfile?</h3> | ||
| <p class="mb-4"> | ||
| Gemfiles are used to manage dependencies. Usually, most gems in a Gemfile are not service related, so that makes it harder to find the ones that are services. | ||
| </p> | ||
| </div> | ||
|
|
||
| <div class="mb-4"> | ||
| <h3 class="text-2xl font-semibold mb-2">Why not just use a README?</h3> | ||
| <p class="mb-4"> | ||
| README files are often very long and take a considerable amount of time to read. | ||
| </p> | ||
| </div> | ||
|
|
||
| <div class="mb-4"> | ||
| <h3 class="text-2xl font-semibold mb-2">Do I have to use valid YAML?</h3> | ||
| <p class="mb-4"> | ||
| No, not at all. Just start with YAML. But, if you need to use non-YAML syntax later, that's fine. This is <em>your</em> list. | ||
| </p> | ||
| </div> | ||
|
|
||
| <div class="mb-4 last:mb-0"> | ||
| <h3 class="text-2xl font-semibold mb-2">Is this format supposed to be machine-parseable?</h3> | ||
| <p> | ||
| Not really, but you're welcome to do so. | ||
| </p> | ||
| </div> | ||
|
|
||
| <div class="mb-4 last:mb-0"> | ||
| <h3 class="text-2xl font-semibold mb-2">Can I use this without Rails?</h3> | ||
| <p> | ||
| Sure! This format can be used with any kind of web app. | ||
| </p> | ||
| </div> | ||
| </section> | ||
|
|
||
| <footer class="bg-gray-800 p-4 rounded-lg text-center text-white"> | ||
| <p class="text-sm">Shared under the MIT license. Copyright © 2024 Patrick Crowley.</p> | ||
| </footer> | ||
| </div> | ||
| </body> | ||
| </html> |