Skip to content

Commit

Permalink
docs: publish a jekyll documentation page
Browse files Browse the repository at this point in the history
  • Loading branch information
wowu committed Dec 21, 2024
1 parent 7487c2d commit fdc7b21
Show file tree
Hide file tree
Showing 19 changed files with 635 additions and 40 deletions.
61 changes: 61 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Sample workflow for building and deploying a Jekyll site to GitHub Pages
name: Deploy Jekyll site to Pages

on:
push:
branches: ["main"]

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true

jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.3' # Not needed with a .ruby-version file
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
cache-version: 0 # Increment this number if you need to re-download cached gems
working-directory: docs
- name: Setup Pages
id: pages
uses: actions/configure-pages@v5
- name: Build with Jekyll
working-directory: docs
# Outputs to the './_site' directory by default
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
env:
JEKYLL_ENV: production
- name: Upload artifact
# Automatically uploads an artifact from the './_site' directory by default
uses: actions/upload-pages-artifact@v3
with:
path: docs/_site

# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Options:
- `--wait-after-healthy SECONDS` - (not required) - Time to wait after new container is healthy before removing old container. Works when healthcheck is defined. Default: 0
- `--env-file FILE` - (not required) - Path to env file, can be specified multiple times, as in `docker compose`.

See examples in [examples](examples) directory for sample `docker-compose.yml` files.
See [examples](docs/examples) for sample `docker-compose.yml` files.

### ⚠️ Caveats

Expand Down
9 changes: 9 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Ignore the default location of the built site, and caches and metadata generated by Jekyll
_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata

# Ignore folders generated by Bundler
.bundle/
vendor/
10 changes: 10 additions & 0 deletions docs/404.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
permalink: /404.html
---

## 404 - Page Not Found

Return to the [home page](/).

<!-- Track 404 page views to catch broken links -->
<script>document.addEventListener('DOMContentLoaded', function () { plausible('404', { props: { path: document.location.pathname } }); });</script>
8 changes: 8 additions & 0 deletions docs/Gemfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
source 'https://rubygems.org'

gem "jekyll", "~> 4.3.4" # installed by `gem jekyll`
# gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2

gem "just-the-docs", "0.10.0" # pinned to the current release
# gem "just-the-docs" # always download the latest release
gem "jekyll-default-layout"
94 changes: 94 additions & 0 deletions docs/Gemfile.lock
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
GEM
remote: https://rubygems.org/
specs:
addressable (2.8.7)
public_suffix (>= 2.0.2, < 7.0)
bigdecimal (3.1.8)
colorator (1.1.0)
concurrent-ruby (1.3.4)
em-websocket (0.5.3)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0)
eventmachine (1.2.7)
ffi (1.17.0-arm64-darwin)
ffi (1.17.0-x86_64-linux-gnu)
forwardable-extended (2.6.0)
google-protobuf (4.28.1-arm64-darwin)
bigdecimal
rake (>= 13)
google-protobuf (4.28.1-x86_64-linux)
bigdecimal
rake (>= 13)
http_parser.rb (0.8.0)
i18n (1.14.6)
concurrent-ruby (~> 1.0)
jekyll (4.3.4)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
i18n (~> 1.0)
jekyll-sass-converter (>= 2.0, < 4.0)
jekyll-watch (~> 2.0)
kramdown (~> 2.3, >= 2.3.1)
kramdown-parser-gfm (~> 1.0)
liquid (~> 4.0)
mercenary (>= 0.3.6, < 0.5)
pathutil (~> 0.9)
rouge (>= 3.0, < 5.0)
safe_yaml (~> 1.0)
terminal-table (>= 1.8, < 4.0)
webrick (~> 1.7)
jekyll-default-layout (0.1.5)
jekyll (>= 3.0, < 5.0)
jekyll-include-cache (0.2.1)
jekyll (>= 3.7, < 5.0)
jekyll-sass-converter (3.0.0)
sass-embedded (~> 1.54)
jekyll-seo-tag (2.8.0)
jekyll (>= 3.8, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
just-the-docs (0.10.0)
jekyll (>= 3.8.5)
jekyll-include-cache
jekyll-seo-tag (>= 2.0)
rake (>= 12.3.1)
kramdown (2.4.0)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.4)
listen (3.9.0)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.4.0)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (6.0.1)
rake (13.2.1)
rb-fsevent (0.11.2)
rb-inotify (0.11.1)
ffi (~> 1.0)
rexml (3.3.7)
rouge (4.3.0)
safe_yaml (1.0.5)
sass-embedded (1.78.0-arm64-darwin)
google-protobuf (~> 4.27)
sass-embedded (1.78.0-x86_64-linux-gnu)
google-protobuf (~> 4.27)
terminal-table (3.0.2)
unicode-display_width (>= 1.1.1, < 3)
unicode-display_width (2.6.0)
webrick (1.8.1)

PLATFORMS
arm64-darwin
x86_64-linux-gnu

DEPENDENCIES
jekyll (~> 4.3.4)
jekyll-default-layout
just-the-docs (= 0.10.0)

BUNDLED WITH
2.5.9
22 changes: 22 additions & 0 deletions docs/_config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
title: docker rollout
description: 🚀 Zero Downtime Deployment for Docker Compose.
theme: just-the-docs
url: https://docker-rollout.wowu.dev

# just-the-docs theme config
aux_links:
GitHub Repository: https://github.com/wowu/docker-rollout
nav_external_links:
- title: GitHub
url: https://github.com/wowu/docker-rollout
hide_icon: false # set to true to hide the external link icon - defaults to false
opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
callouts:
warning:
title: Warning
color: red
search:
focus_shortcut_key: 'k'

plugins:
- jekyll-default-layout
2 changes: 2 additions & 0 deletions docs/_includes/head_custom.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<script defer data-domain="docker-rollout.wowu.dev" src="https://a.musur.pl/js/script.hash.outbound-links.js"></script>
<script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>
102 changes: 102 additions & 0 deletions docs/cli-options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
title: CLI Options
nav_order: 3
---

# CLI Options
{: .no_toc }

1. TOC
{:toc}


## Docker flags

All docker flags can be used with `docker rollout` normally, like `--context`, `--env`, `--log-level`, etc.

```bash
docker --context my-remote-context rollout <service-name>
```

The plugin flags are described below.

## `-f | --file FILE`

Path to compose file, can be specified multiple times, as in `docker compose`.

**Example**

Single file:

```bash
docker rollout -f docker-compose.yml <service-name>
```

With override file:

```bash
docker rollout -f docker-compose.yml -f docker-compose.override.yml <service-name>
```

## `-t | --timeout SECONDS`

Timeout in seconds to wait for new container to become healthy, if the container has healthcheck defined.

Default: 60

**Example**

Decrease timeout to 30 seconds:

```bash
docker rollout --timeout 30 <service-name>
```

## `-w | --wait SECONDS`

Time to wait for new container to be ready if healthcheck is not defined.

Default: 10

**Example**

Increase wait time to 30 seconds for a service that takes longer to start:

```bash
docker rollout --wait 30 <service-name>
```

## `--wait-after-healthy SECONDS`

Time to wait after new container is healthy before removing old container. Works when a healthcheck is defined. Can be useful if the service healthcheck is not reliable and the service needs some time to stabilize (see [#27](https://github.com/wowu/docker-rollout/issues/27)).

Default: 0

**Example**

Wait 10 seconds after a new container is healthy before terminating the old container:

```bash
docker rollout --wait-after-healthy 10 <service-name>
```

## `--env-file FILE`

Path to env file, can be specified multiple times, like in `docker compose`.

See [Docker Compose documentation](https://docs.docker.com/reference/cli/docker/compose/).

**Example**

Single env file:

```bash
docker rollout --env-file .env <service-name>
```

Multiple env files:

```bash
docker rollout --env-file .env --env-file .env.prod <service-name>
```

6 changes: 6 additions & 0 deletions docs/examples/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
title: Examples
---

# Examples

43 changes: 43 additions & 0 deletions docs/examples/nginx_proxy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: Nginx Proxy
parent: Examples
---

# Nginx Proxy

Works with Docker Compose v2.

## Compose file

```yml
services:
whoami:
image: jwilder/whoami
environment:
- VIRTUAL_HOST=whoami.example.com

nginx-proxy:
image: nginxproxy/nginx-proxy
ports:
- "80:80"
volumes:
- /var/run/docker.sock:/tmp/docker.sock:ro
```
## Steps
1. Change domain in `docker-compose.yml` to a domain pointing to your server

2. Start all services

```bash
docker-compose up -d
```

3. Change `whoami` image to, for example, `traefik/whoami`.

4. Deploy a new version of `whoami` service without downtime.

```bash
docker rollout whoami
```
Loading

0 comments on commit fdc7b21

Please sign in to comment.