beaker-docker 0.8.3 → 1.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (15) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/release.yml +16 -8
  3. data/.github/workflows/test.yml +15 -21
  4. data/CHANGELOG.md +224 -0
  5. data/Gemfile +11 -2
  6. data/Gemfile.local +0 -2
  7. data/README.md +26 -4
  8. data/Rakefile +14 -0
  9. data/beaker-docker.gemspec +2 -5
  10. data/docker.md +4 -0
  11. data/lib/beaker/hypervisor/docker.rb +71 -26
  12. data/lib/beaker-docker/version.rb +1 -1
  13. data/spec/beaker/hypervisor/docker_spec.rb +45 -6
  14. data/spec/spec_helper.rb +24 -1
  15. metadata +16 -29
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 334f12192e1c187506529fd753491a8aba885ccf5512d2f681b7b659f4b7f525
4
- data.tar.gz: ee99cc4537be2eb938639fd4078aa1f95eba859b338531ba206c4035587e103a
3
+ metadata.gz: 296226435995d98cfeffeb61804ac77e25bd446c8d795610b40957940f8a3a66
4
+ data.tar.gz: bd0acc21e9bccf2787b743d1e4c927d6a11d81746f595227a020d1881f6c203e
5
5
  SHA512:
6
- metadata.gz: 9df1580cf398c8b43641d9b06e53be3090d2141fd9a9172c1f1a6290f362b5d02819e720ee05046e024c4051a8201001569663feb7716263616f578b0d66fbac
7
- data.tar.gz: 9e1d910176b66e2576cb170f31b80a97491274248a698c89c5925413c35165afc96cd9da9e4ba2acd4fcd1dea548cec5753211ed796ff0e84a91edce9719ce49
6
+ metadata.gz: c17ec27c00fe4bc5b4397c65b9d13f3154d172795c1a4306f26af2caef9dbcbd3c336c430fde0479a09c42c754b592cc26870ddce3cfbb58d07248382ab1364e
7
+ data.tar.gz: d75961b6868c5b512b9dd8948d9a51d02d6a0cd24763ed4d275af81dfa16748f099eb72f3ac4d70bf50466dd41a1f4a6d7bfa258205952353adcad5d653fdef9
data/.github/workflows/release.yml CHANGED
@@ -1,24 +1,32 @@
1
1
  name: Release
2
2
 
3
3
  on:
4
- create:
5
- ref_type: tag
4
+ push:
5
+ tags:
6
+ - '*'
6
7
 
7
8
  jobs:
8
9
  release:
9
10
  runs-on: ubuntu-latest
10
- if: github.repository == 'voxpupuli/beaker-docker'
11
- env:
12
- BUNDLE_WITHOUT: release
11
+ if: github.repository_owner == 'voxpupuli'
13
12
  steps:
14
13
  - uses: actions/checkout@v2
15
- - name: Install Ruby 2.7
14
+ - name: Install Ruby 3.0
16
15
  uses: ruby/setup-ruby@v1
17
16
  with:
18
- ruby-version: '2.7'
17
+ ruby-version: '3.0'
18
+ env:
19
+ BUNDLE_WITHOUT: release
19
20
  - name: Build gem
20
21
  run: gem build *.gemspec
21
- - name: Publish gem
22
+ - name: Publish gem to rubygems.org
22
23
  run: gem push *.gem
23
24
  env:
24
25
  GEM_HOST_API_KEY: '${{ secrets.RUBYGEMS_AUTH_TOKEN }}'
26
+ - name: Setup GitHub packages access
27
+ run: |
28
+ mkdir -p ~/.gem
29
+ echo ":github: Bearer ${{ secrets.GITHUB_TOKEN }}" >> ~/.gem/credentials
30
+ chmod 0600 ~/.gem/credentials
31
+ - name: Publish gem to GitHub packages
32
+ run: gem push --key github --host https://rubygems.pkg.github.com/voxpupuli *.gem
data/.github/workflows/test.yml CHANGED
@@ -1,13 +1,11 @@
1
1
  name: Test
2
2
 
3
3
  on:
4
- push:
5
- branches:
6
- - test_me_github
7
- pull_request:
8
- branches:
9
- - main
10
- - master
4
+ - pull_request
5
+ - push
6
+
7
+ env:
8
+ BUNDLE_WITHOUT: release
11
9
 
12
10
  jobs:
13
11
  rspec:
@@ -15,13 +13,15 @@ jobs:
15
13
  strategy:
16
14
  fail-fast: true
17
15
  matrix:
18
- ruby:
19
- - "2.4"
20
- - "2.5"
21
- - "2.6"
22
- - "2.7"
16
+ include:
17
+ - ruby: "2.4"
18
+ - ruby: "2.5"
19
+ - ruby: "2.6"
20
+ - ruby: "2.7"
21
+ - ruby: "3.0"
22
+ coverage: "yes"
23
23
  env:
24
- BUNDLE_WITHOUT: release
24
+ COVERAGE: ${{ matrix.coverage }}
25
25
  name: RSpec - Ruby ${{ matrix.ruby }}
26
26
  steps:
27
27
  - uses: actions/checkout@v2
@@ -30,12 +30,10 @@ jobs:
30
30
  with:
31
31
  ruby-version: ${{ matrix.ruby }}
32
32
  bundler-cache: true
33
- - name: install bundler
34
- run: |
35
- gem install bundler -v '~> 1.17.3'
36
- bundle update
37
33
  - name: spec tests
38
34
  run: bundle exec rake test:spec
35
+ - name: Build gem
36
+ run: gem build *.gemspec
39
37
 
40
38
  docker:
41
39
  runs-on: ubuntu-latest
@@ -44,8 +42,6 @@ jobs:
44
42
  matrix:
45
43
  ruby:
46
44
  - "2.6"
47
- env:
48
- BUNDLE_WITHOUT: release
49
45
  name: Docker - Ruby ${{ matrix.ruby }}
50
46
  steps:
51
47
  - uses: actions/checkout@v2
@@ -78,8 +74,6 @@ jobs:
78
74
  matrix:
79
75
  ruby:
80
76
  - "2.6"
81
- env:
82
- BUNDLE_WITHOUT: release
83
77
  name: Podman - Ruby ${{ matrix.ruby }}
84
78
  steps:
85
79
  - uses: actions/checkout@v2
data/CHANGELOG.md ADDED
@@ -0,0 +1,224 @@
1
+ # Changelog
2
+
3
+ ## [1.1.0](https://github.com/voxpupuli/beaker-docker/tree/1.1.0) (2022-01-27)
4
+
5
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/1.0.1...1.1.0)
6
+
7
+ **Implemented enhancements:**
8
+
9
+ - Use host\_packages helper to reuse logic from beaker [\#59](https://github.com/voxpupuli/beaker-docker/pull/59) ([ekohl](https://github.com/ekohl))
10
+
11
+ ## [1.0.1](https://github.com/voxpupuli/beaker-docker/tree/1.0.1) (2021-09-13)
12
+
13
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/1.0.0...1.0.1)
14
+
15
+ **Implemented enhancements:**
16
+
17
+ - Initial EL9 support [\#55](https://github.com/voxpupuli/beaker-docker/pull/55) ([ekohl](https://github.com/ekohl))
18
+ - Add support for additional Docker port bindings [\#54](https://github.com/voxpupuli/beaker-docker/pull/54) ([treydock](https://github.com/treydock))
19
+
20
+ **Fixed bugs:**
21
+
22
+ - Fix IP detection in WSL2 environments [\#56](https://github.com/voxpupuli/beaker-docker/pull/56) ([trevor-vaughan](https://github.com/trevor-vaughan))
23
+ - Fix SSH port binding [\#53](https://github.com/voxpupuli/beaker-docker/pull/53) ([treydock](https://github.com/treydock))
24
+ - Added ENV DOCKER\_IN\_DOCKER to fix SSH conn info [\#51](https://github.com/voxpupuli/beaker-docker/pull/51) ([QueerCodingGirl](https://github.com/QueerCodingGirl))
25
+
26
+ **Closed issues:**
27
+
28
+ - Regression with 1.0.0 WRT SSH port usage [\#52](https://github.com/voxpupuli/beaker-docker/issues/52)
29
+
30
+ ## [1.0.0](https://github.com/voxpupuli/beaker-docker/tree/1.0.0) (2021-08-06)
31
+
32
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.8.4...1.0.0)
33
+
34
+ **Implemented enhancements:**
35
+
36
+ - Implement codecov reporting [\#49](https://github.com/voxpupuli/beaker-docker/pull/49) ([bastelfreak](https://github.com/bastelfreak))
37
+
38
+ **Fixed bugs:**
39
+
40
+ - Treat Fedora 22+ and EL8 the same [\#48](https://github.com/voxpupuli/beaker-docker/pull/48) ([ekohl](https://github.com/ekohl))
41
+ - Be more aggressive about picking a connection [\#47](https://github.com/voxpupuli/beaker-docker/pull/47) ([trevor-vaughan](https://github.com/trevor-vaughan))
42
+
43
+ ## [0.8.4](https://github.com/voxpupuli/beaker-docker/tree/0.8.4) (2021-03-15)
44
+
45
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.8.3...0.8.4)
46
+
47
+ **Fixed bugs:**
48
+
49
+ - Force Container Removal [\#45](https://github.com/voxpupuli/beaker-docker/pull/45) ([trevor-vaughan](https://github.com/trevor-vaughan))
50
+
51
+ **Closed issues:**
52
+
53
+ - Wrong SSH port getting used [\#43](https://github.com/voxpupuli/beaker-docker/issues/43)
54
+ - Beaker complains about host unreachable - Ubuntu 18 and 20 [\#39](https://github.com/voxpupuli/beaker-docker/issues/39)
55
+
56
+ **Merged pull requests:**
57
+
58
+ - Fix docker usage to use correct port and IP address on local docker [\#44](https://github.com/voxpupuli/beaker-docker/pull/44) ([treydock](https://github.com/treydock))
59
+ - Update to Check Rootless [\#41](https://github.com/voxpupuli/beaker-docker/pull/41) ([trevor-vaughan](https://github.com/trevor-vaughan))
60
+ - Change from my personal fork to docker-api 2.1+ [\#40](https://github.com/voxpupuli/beaker-docker/pull/40) ([trevor-vaughan](https://github.com/trevor-vaughan))
61
+
62
+ ## [0.8.3](https://github.com/voxpupuli/beaker-docker/tree/0.8.3) (2021-02-28)
63
+
64
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.8.2...0.8.3)
65
+
66
+ **Merged pull requests:**
67
+
68
+ - Cleanup docs and gemspec [\#37](https://github.com/voxpupuli/beaker-docker/pull/37) ([genebean](https://github.com/genebean))
69
+
70
+ ## [0.8.2](https://github.com/voxpupuli/beaker-docker/tree/0.8.2) (2021-02-28)
71
+
72
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.8.1...0.8.2)
73
+
74
+ **Merged pull requests:**
75
+
76
+ - Deconflict Privileged and CAPs [\#34](https://github.com/voxpupuli/beaker-docker/pull/34) ([trevor-vaughan](https://github.com/trevor-vaughan))
77
+
78
+ ## [0.8.1](https://github.com/voxpupuli/beaker-docker/tree/0.8.1) (2021-02-28)
79
+
80
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.8.0...0.8.1)
81
+
82
+ **Merged pull requests:**
83
+
84
+ - Fix docker support and update github actions [\#32](https://github.com/voxpupuli/beaker-docker/pull/32) ([trevor-vaughan](https://github.com/trevor-vaughan))
85
+ - Add GH Action for releases [\#31](https://github.com/voxpupuli/beaker-docker/pull/31) ([genebean](https://github.com/genebean))
86
+
87
+ ## [0.8.0](https://github.com/voxpupuli/beaker-docker/tree/0.8.0) (2021-02-26)
88
+
89
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.7.1...0.8.0)
90
+
91
+ **Merged pull requests:**
92
+
93
+ - Move testing to GH Actions [\#30](https://github.com/voxpupuli/beaker-docker/pull/30) ([genebean](https://github.com/genebean))
94
+ - Add Podman Support [\#29](https://github.com/voxpupuli/beaker-docker/pull/29) ([trevor-vaughan](https://github.com/trevor-vaughan))
95
+
96
+ ## [0.7.1](https://github.com/voxpupuli/beaker-docker/tree/0.7.1) (2020-09-11)
97
+
98
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.7.0...0.7.1)
99
+
100
+ **Merged pull requests:**
101
+
102
+ - Fix: docker-api gem dependency [\#26](https://github.com/voxpupuli/beaker-docker/pull/26) ([msalway](https://github.com/msalway))
103
+ - Add Dependabot to keep thins up to date [\#23](https://github.com/voxpupuli/beaker-docker/pull/23) ([genebean](https://github.com/genebean))
104
+
105
+ ## [0.7.0](https://github.com/voxpupuli/beaker-docker/tree/0.7.0) (2020-01-23)
106
+
107
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.6.0...0.7.0)
108
+
109
+ **Merged pull requests:**
110
+
111
+ - Fix: Too many authentication failures [\#21](https://github.com/voxpupuli/beaker-docker/pull/21) ([b4ldr](https://github.com/b4ldr))
112
+ - \(MAINT\) add release section to README [\#20](https://github.com/voxpupuli/beaker-docker/pull/20) ([kevpl](https://github.com/kevpl))
113
+
114
+ ## [0.6.0](https://github.com/voxpupuli/beaker-docker/tree/0.6.0) (2019-11-12)
115
+
116
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.5.4...0.6.0)
117
+
118
+ **Merged pull requests:**
119
+
120
+ - \(BKR-1613\) add CentOS8 support [\#19](https://github.com/voxpupuli/beaker-docker/pull/19) ([ciprianbadescu](https://github.com/ciprianbadescu))
121
+
122
+ ## [0.5.4](https://github.com/voxpupuli/beaker-docker/tree/0.5.4) (2019-07-15)
123
+
124
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.5.3...0.5.4)
125
+
126
+ **Merged pull requests:**
127
+
128
+ - \(maint\) A number of fixes for rerunning tests on docker containers [\#18](https://github.com/voxpupuli/beaker-docker/pull/18) ([underscorgan](https://github.com/underscorgan))
129
+
130
+ ## [0.5.3](https://github.com/voxpupuli/beaker-docker/tree/0.5.3) (2019-05-06)
131
+
132
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.5.2...0.5.3)
133
+
134
+ **Merged pull requests:**
135
+
136
+ - BKR-1586 - allow an 'as-is' container to be used rather than rebuilding every time [\#17](https://github.com/voxpupuli/beaker-docker/pull/17) ([oldNoakes](https://github.com/oldNoakes))
137
+
138
+ ## [0.5.2](https://github.com/voxpupuli/beaker-docker/tree/0.5.2) (2019-02-11)
139
+
140
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.5.1...0.5.2)
141
+
142
+ **Merged pull requests:**
143
+
144
+ - Allow users with large keyrings to run test [\#16](https://github.com/voxpupuli/beaker-docker/pull/16) ([trevor-vaughan](https://github.com/trevor-vaughan))
145
+
146
+ ## [0.5.1](https://github.com/voxpupuli/beaker-docker/tree/0.5.1) (2018-11-29)
147
+
148
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.5.0...0.5.1)
149
+
150
+ **Merged pull requests:**
151
+
152
+ - \(SERVER-2380\) add image tagging ability [\#14](https://github.com/voxpupuli/beaker-docker/pull/14) ([tvpartytonight](https://github.com/tvpartytonight))
153
+
154
+ ## [0.5.0](https://github.com/voxpupuli/beaker-docker/tree/0.5.0) (2018-11-19)
155
+
156
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.4.0...0.5.0)
157
+
158
+ **Merged pull requests:**
159
+
160
+ - \(BKR-1551\) Updates for Beaker 4 [\#13](https://github.com/voxpupuli/beaker-docker/pull/13) ([caseywilliams](https://github.com/caseywilliams))
161
+
162
+ ## [0.4.0](https://github.com/voxpupuli/beaker-docker/tree/0.4.0) (2018-10-26)
163
+
164
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.3.3...0.4.0)
165
+
166
+ **Merged pull requests:**
167
+
168
+ - \(PUP-9212\) Allow for building containers with context [\#12](https://github.com/voxpupuli/beaker-docker/pull/12) ([tvpartytonight](https://github.com/tvpartytonight))
169
+ - \(PUP-9212\) Allow for image entry point CMDs [\#11](https://github.com/voxpupuli/beaker-docker/pull/11) ([tvpartytonight](https://github.com/tvpartytonight))
170
+ - \(BKR-1509\) Hypervisor usage instructions for Beaker 4..0 [\#9](https://github.com/voxpupuli/beaker-docker/pull/9) ([Dakta](https://github.com/Dakta))
171
+
172
+ ## [0.3.3](https://github.com/voxpupuli/beaker-docker/tree/0.3.3) (2018-04-16)
173
+
174
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.3.2...0.3.3)
175
+
176
+ **Merged pull requests:**
177
+
178
+ - \(BKR-305\) Support custom docker options [\#8](https://github.com/voxpupuli/beaker-docker/pull/8) ([double16](https://github.com/double16))
179
+
180
+ ## [0.3.2](https://github.com/voxpupuli/beaker-docker/tree/0.3.2) (2018-04-09)
181
+
182
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.3.1...0.3.2)
183
+
184
+ **Merged pull requests:**
185
+
186
+ - \(MAINT\) fix paths when using DOCKER\_TOOLBOX on windows [\#7](https://github.com/voxpupuli/beaker-docker/pull/7) ([tabakhase](https://github.com/tabakhase))
187
+
188
+ ## [0.3.1](https://github.com/voxpupuli/beaker-docker/tree/0.3.1) (2018-02-22)
189
+
190
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.3.0...0.3.1)
191
+
192
+ **Merged pull requests:**
193
+
194
+ - Fix Archlinux support [\#6](https://github.com/voxpupuli/beaker-docker/pull/6) ([bastelfreak](https://github.com/bastelfreak))
195
+
196
+ ## [0.3.0](https://github.com/voxpupuli/beaker-docker/tree/0.3.0) (2018-01-29)
197
+
198
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.2.0...0.3.0)
199
+
200
+ **Merged pull requests:**
201
+
202
+ - \[BKR-1021\] Archlinux support [\#5](https://github.com/voxpupuli/beaker-docker/pull/5) ([jantman](https://github.com/jantman))
203
+ - Don't set container name to node hostname [\#4](https://github.com/voxpupuli/beaker-docker/pull/4) ([jovrum](https://github.com/jovrum))
204
+
205
+ ## [0.2.0](https://github.com/voxpupuli/beaker-docker/tree/0.2.0) (2017-08-11)
206
+
207
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/0.1.0...0.2.0)
208
+
209
+ **Merged pull requests:**
210
+
211
+ - \(BKR-1189\) Fix port mapping [\#3](https://github.com/voxpupuli/beaker-docker/pull/3) ([rishijavia](https://github.com/rishijavia))
212
+ - Make beaker-docker work in a docker container [\#2](https://github.com/voxpupuli/beaker-docker/pull/2) ([hedinasr](https://github.com/hedinasr))
213
+
214
+ ## [0.1.0](https://github.com/voxpupuli/beaker-docker/tree/0.1.0) (2017-08-01)
215
+
216
+ [Full Changelog](https://github.com/voxpupuli/beaker-docker/compare/7f6a78541f30385016478e810ecb0c14f3936e20...0.1.0)
217
+
218
+ **Merged pull requests:**
219
+
220
+ - \(MAINT\) Add docker-api dependency as its removed from beaker [\#1](https://github.com/voxpupuli/beaker-docker/pull/1) ([rishijavia](https://github.com/rishijavia))
221
+
222
+
223
+
224
+ \* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*
data/Gemfile CHANGED
@@ -1,4 +1,4 @@
1
- source ENV['GEM_SOURCE'] || "https://rubygems.org"
1
+ source ENV['GEM_SOURCE'] || 'https://rubygems.org'
2
2
 
3
3
  gemspec
4
4
 
@@ -16,10 +16,19 @@ end
16
16
  # We don't put beaker in as a test dependency because we
17
17
  # don't want to create a transitive dependency
18
18
  group :acceptance_testing do
19
- gem "beaker", *location_for(ENV['BEAKER_VERSION'] || '~> 4.0')
19
+ gem "beaker", *location_for(ENV['BEAKER_VERSION'] || '>= 4.30')
20
20
  end
21
21
 
22
22
 
23
23
  if File.exists? "#{__FILE__}.local"
24
24
  eval(File.read("#{__FILE__}.local"), binding)
25
25
  end
26
+
27
+ group :coverage, optional: ENV['COVERAGE']!='yes' do
28
+ gem 'simplecov-console', :require => false
29
+ gem 'codecov', :require => false
30
+ end
31
+
32
+ group :release do
33
+ gem 'github_changelog_generator', require: false
34
+ end
data/Gemfile.local CHANGED
@@ -1,5 +1,3 @@
1
1
  group :acceptance_testing do
2
- # Needed for podman testing
3
- gem "docker-api", :git => 'https://github.com/trevor-vaughan/docker-api', :branch => 'podman-compat'
4
2
  gem "beaker-rspec"
5
3
  end
data/README.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # beaker-docker
2
2
 
3
+ [![License](https://img.shields.io/github/license/voxpupuli/beaker-docker.svg)](https://github.com/voxpupuli/beaker-docker/blob/master/LICENSE)
4
+ [![Test](https://github.com/voxpupuli/beaker-docker/actions/workflows/test.yml/badge.svg)](https://github.com/voxpupuli/beaker-docker/actions/workflows/test.yml)
5
+ [![codecov](https://codecov.io/gh/voxpupuli/beaker-docker/branch/master/graph/badge.svg?token=Mypkl78hvK)](https://codecov.io/gh/voxpupuli/beaker-docker)
6
+ [![Release](https://github.com/voxpupuli/beaker-docker/actions/workflows/release.yml/badge.svg)](https://github.com/voxpupuli/beaker-docker/actions/workflows/release.yml)
7
+ [![RubyGem Version](https://img.shields.io/gem/v/beaker-docker.svg)](https://rubygems.org/gems/beaker-docker)
8
+ [![RubyGem Downloads](https://img.shields.io/gem/dt/beaker-docker.svg)](https://rubygems.org/gems/beaker-docker)
9
+ [![Donated by Puppet Inc](https://img.shields.io/badge/donated%20by-Puppet%20Inc-fb7047.svg)](#transfer-notice)
10
+
3
11
  Beaker library to use docker hypervisor
4
12
 
5
13
  ## How to use this wizardry
@@ -110,10 +118,24 @@ There is a simple rake task to invoke acceptance test for the library:
110
118
  bundle exec rake test:acceptance
111
119
  ```
112
120
 
113
- ## Contributing
121
+ ## Transfer Notice
122
+
123
+ This plugin was originally authored by [Puppet Inc](http://puppet.com).
124
+ The maintainer preferred that Puppet Community take ownership of the module for future improvement and maintenance.
125
+ Existing pull requests and issues were transferred over, please fork and continue to contribute here.
126
+
127
+ Previously: https://github.com/puppetlabs/beaker
128
+
129
+ ## License
114
130
 
115
- Please refer to puppetlabs/beaker's [contributing](https://github.com/puppetlabs/beaker/blob/master/CONTRIBUTING.md) guide.
131
+ This gem is licensed under the Apache-2 license.
116
132
 
117
- ## Releasing
133
+ ## Release information
118
134
 
119
- To release new versions of beaker-docker, please use update `lib/beaker-docker/version.rb` with the new version number. The version should adhere to [semantic version standards](https://semver.org). When in doubt, ask in the `#voxpupuli` channel of the Puppet community Slack or in `#voxpupuli` on irc.freenode.net ([Webinterface](https://webchat.freenode.net/?channels=%23voxpupuli)).
135
+ To make a new release, please do:
136
+ * update the version in `lib/beaker-docker/version.rb`
137
+ * Install gems with `bundle install --with release --path .vendor`
138
+ * generate the changelog with `bundle exec rake changelog`
139
+ * Check if the new version matches the closed issues/PRs in the changelog
140
+ * Create a PR with it
141
+ * After it got merged, push a tag. GitHub actions will do the actual release to rubygems and GitHub Packages
data/Rakefile CHANGED
@@ -163,3 +163,17 @@ namespace :docs do
163
163
  end
164
164
  end
165
165
  end
166
+
167
+ begin
168
+ require 'rubygems'
169
+ require 'github_changelog_generator/task'
170
+ rescue LoadError
171
+ else
172
+ GitHubChangelogGenerator::RakeTask.new :changelog do |config|
173
+ config.exclude_labels = %w{duplicate question invalid wontfix wont-fix skip-changelog}
174
+ config.user = 'voxpupuli'
175
+ config.project = 'beaker-docker'
176
+ gem_version = Gem::Specification.load("#{config.project}.gemspec").version
177
+ config.future_release = gem_version
178
+ end
179
+ end
data/beaker-docker.gemspec CHANGED
@@ -27,12 +27,9 @@ Gem::Specification.new do |s|
27
27
  s.add_development_dependency 'rspec-its', '~> 1.3'
28
28
  s.add_development_dependency 'fakefs', '~> 1.3'
29
29
  s.add_development_dependency 'rake', '~> 13.0'
30
- s.add_development_dependency 'simplecov', '~> 0.18'
31
- s.add_development_dependency 'pry', '~> 0.10'
32
30
 
33
31
  # Run time dependencies
34
32
  s.add_runtime_dependency 'stringify-hash', '~> 0.0.0'
35
- s.add_runtime_dependency 'docker-api', '< 3.0.0'
36
-
33
+ s.add_runtime_dependency 'docker-api', '~> 2.1'
34
+ s.add_runtime_dependency 'beaker', '>= 4.34'
37
35
  end
38
-
data/docker.md CHANGED
@@ -188,3 +188,7 @@ node available as ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=
188
188
  ```
189
189
 
190
190
  The tests should then run as normal from there.
191
+
192
+
193
+ ### Docker-in-Docker (dind) ###
194
+ If you are using docker in docker, set the environment variable DOCKER_IN_DOCKER=true. Beaker-docker will then not try to use the DOCKER_HOST address for the ssh connection to the containers.
data/lib/beaker/hypervisor/docker.rb CHANGED
@@ -44,6 +44,8 @@ module Beaker
44
44
  else
45
45
  @registry = ENV['DOCKER_REGISTRY']
46
46
  end
47
+ elsif ::Docker.respond_to?(:podman?) && ::Docker.podman?
48
+ @docker_type = 'podman'
47
49
  else
48
50
  @docker_type = 'docker'
49
51
  end
@@ -125,6 +127,11 @@ module Beaker
125
127
  { rm: true, buildargs: buildargs_for(host) })
126
128
  end
127
129
 
130
+ # Nested Docker scenarios
131
+ def nested_docker?
132
+ ENV['DOCKER_IN_DOCKER'] || ENV['WSLENV']
133
+ end
134
+
128
135
  # Find out where the ssh port is from the container
129
136
  # When running on swarm DOCKER_HOST points to the swarm manager so we have to get the
130
137
  # IP of the swarm slave via the container data
@@ -142,21 +149,57 @@ module Beaker
142
149
  ip = nil
143
150
  port = nil
144
151
  # Talking against a remote docker host which is a normal docker host
145
- if @docker_type == 'docker' && ENV['DOCKER_HOST'] && !ENV.fetch('DOCKER_HOST','').include?(':///')
152
+ if @docker_type == 'docker' && ENV['DOCKER_HOST'] && !ENV.fetch('DOCKER_HOST','').include?(':///') && !nested_docker?
146
153
  ip = URI.parse(ENV['DOCKER_HOST']).host
147
154
  else
148
155
  # Swarm or local docker host
149
- if in_container?
156
+ if in_container? && !nested_docker?
150
157
  gw = network_settings['Gateway']
151
158
  ip = gw unless (gw.nil? || gw.empty?)
152
159
  else
153
- port22 = network_settings.dig('Ports','22/tcp')
154
- ip = port22[0]["HostIp"] if port22
160
+ # The many faces of container networking
161
+
162
+ # Host to Container
163
+ port22 = network_settings.dig('PortBindings','22/tcp')
164
+ if port22.nil? && network_settings.key?('Ports')
165
+ port22 = network_settings.dig('Ports','22/tcp')
166
+ end
167
+ ip = port22[0]['HostIp'] if port22
168
+ port = port22[0]['HostPort'] if port22
169
+
170
+ # Container to container
171
+ unless ip && port
172
+ ip = nil
173
+ port = nil
174
+
175
+ ip = network_settings['IPAddress']
176
+ port = 22 if ip && !ip.empty?
177
+ end
178
+
179
+ # Container through gateway
180
+ unless ip && port
181
+ ip = nil
182
+ port = nil
183
+
184
+ ip = network_settings['Gateway']
185
+
186
+ if ip && !ip.empty?
187
+ port22 = network_settings.dig('PortBindings','22/tcp')
188
+ port = port22[0]['HostPort'] if port22
189
+ end
190
+ end
191
+
192
+ # Legacy fallback
193
+ unless ip && port
194
+ port22 = network_settings.dig('Ports','22/tcp')
195
+ ip = port22[0]["HostIp"] if port22
196
+ port = port22[0]['HostPort'] if port22
197
+ end
155
198
  end
156
199
  end
157
200
 
158
201
  if host_config['NetworkMode'] != 'slirp4netns' && network_settings['IPAddress'] && !network_settings['IPAddress'].empty?
159
- ip = network_settings['IPAddress']
202
+ ip = network_settings['IPAddress'] if ip.nil?
160
203
  else
161
204
  port22 = network_settings.dig('Ports','22/tcp')
162
205
  port = port22[0]['HostPort'] if port22
@@ -249,6 +292,14 @@ module Beaker
249
292
  container_opts['name'] = ['beaker', host.name, SecureRandom.uuid.split('-').last].join('-')
250
293
  end
251
294
 
295
+ if host['docker_port_bindings']
296
+ container_opts['ExposedPorts'] = {} if container_opts['ExposedPorts'].nil?
297
+ host['docker_port_bindings'].each_pair do |port, bind|
298
+ container_opts['ExposedPorts'][port.to_s] = {}
299
+ container_opts['HostConfig']['PortBindings'][port.to_s] = bind
300
+ end
301
+ end
302
+
252
303
  ### END CONTAINER OPTIONS MANGLING ###
253
304
 
254
305
  @logger.debug("Creating container from image #{image_name}")
@@ -259,10 +310,11 @@ module Beaker
259
310
  container = ::Docker::Container.create(container_opts)
260
311
 
261
312
  ssh_info = get_ssh_connection_info(container)
262
- if ssh_info[:ip] == '127.0.0.1' && (ssh_info[:port].to_i < 1024) && (Process.uid != 0)
263
- @logger.debug("#{host} was given a port less than 1024 but you are not running as root, retrying")
313
+ if ::Docker.rootless? && ssh_info[:ip] == '127.0.0.1' && (ssh_info[:port].to_i < 1024)
314
+ @logger.debug("#{host} was given a port less than 1024 but you are connecting to a rootless instance, retrying")
264
315
 
265
- container.delete
316
+ container.delete(force: true)
317
+ container = nil
266
318
 
267
319
  retries+=1
268
320
  next
@@ -287,7 +339,7 @@ module Beaker
287
339
  begin
288
340
  container.stats
289
341
  rescue StandardError => e
290
- container.delete
342
+ container.delete(force: true)
291
343
  raise "Container '#{container.id}' in a bad state: #{e}"
292
344
  end
293
345
 
@@ -346,7 +398,7 @@ module Beaker
346
398
  container.exec(%w(apt-get update))
347
399
  container.exec(%w(apt-get install -y openssh-server openssh-client))
348
400
  container.exec(%w(sed 's@session\s*required\s*pam_loginuid.so@session optional pam_loginuid.so@g' -i /etc/pam.d/*))
349
- when /fedora-(2[2-9])/
401
+ when /el-[89]/, /fedora-(2[2-9]|3[0-9])/
350
402
  container.exec(%w(dnf clean all))
351
403
  container.exec(%w(dnf install -y sudo openssh-server openssh-clients))
352
404
  container.exec(%w(ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key))
@@ -402,7 +454,7 @@ module Beaker
402
454
  end
403
455
  @logger.debug("delete container #{container.id}")
404
456
  begin
405
- container.delete
457
+ container.delete(force: true)
406
458
  rescue Excon::Errors::ClientError => e
407
459
  @logger.warn("deletion of container #{container.id} failed: #{e.response.body}")
408
460
  end
@@ -470,31 +522,24 @@ module Beaker
470
522
 
471
523
  # add platform-specific actions
472
524
  service_name = "sshd"
525
+ additional_packages = host_packages(host)
473
526
  case host['platform']
474
527
  when /ubuntu/, /debian/
475
528
  service_name = "ssh"
476
529
  dockerfile += <<~EOF
477
530
  RUN apt-get update
478
- RUN apt-get install -y openssh-server openssh-client #{Beaker::HostPrebuiltSteps::DEBIAN_PACKAGES.join(' ')}
531
+ RUN apt-get install -y openssh-server openssh-client #{additional_packages.join(' ')}
479
532
  RUN sed 's@session\s*required\s*pam_loginuid.so@session optional pam_loginuid.so@g' -i /etc/pam.d/*
480
533
  EOF
481
534
  when /cumulus/
482
535
  dockerfile += <<~EOF
483
536
  RUN apt-get update
484
- RUN apt-get install -y openssh-server openssh-client #{Beaker::HostPrebuiltSteps::CUMULUS_PACKAGES.join(' ')}
485
- EOF
486
- when /fedora-(2[2-9])/
487
- dockerfile += <<~EOF
488
- RUN dnf clean all
489
- RUN dnf install -y sudo openssh-server openssh-clients #{Beaker::HostPrebuiltSteps::UNIX_PACKAGES.join(' ')}
490
- RUN ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key
491
- RUN ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key
492
- RUN sed 's@session\s*required\s*pam_loginuid.so@session optional pam_loginuid.so@g' -i /etc/pam.d/*
537
+ RUN apt-get install -y openssh-server openssh-client #{additional_packages.join(' ')}
493
538
  EOF
494
- when /el-8/
539
+ when /el-[89]/, /fedora-(2[2-9]|3)/
495
540
  dockerfile += <<~EOF
496
541
  RUN dnf clean all
497
- RUN dnf install -y sudo openssh-server openssh-clients #{Beaker::HostPrebuiltSteps::RHEL8_PACKAGES.join(' ')}
542
+ RUN dnf install -y sudo openssh-server openssh-clients #{additional_packages.join(' ')}
498
543
  RUN ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key
499
544
  RUN ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key
500
545
  RUN sed 's@session\s*required\s*pam_loginuid.so@session optional pam_loginuid.so@g' -i /etc/pam.d/*
@@ -502,14 +547,14 @@ module Beaker
502
547
  when /^el-/, /centos/, /fedora/, /redhat/, /eos/
503
548
  dockerfile += <<~EOF
504
549
  RUN yum clean all
505
- RUN yum install -y sudo openssh-server openssh-clients #{Beaker::HostPrebuiltSteps::UNIX_PACKAGES.join(' ')}
550
+ RUN yum install -y sudo openssh-server openssh-clients #{additional_packages.join(' ')}
506
551
  RUN ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key
507
552
  RUN ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key
508
553
  RUN sed 's@session\s*required\s*pam_loginuid.so@session optional pam_loginuid.so@g' -i /etc/pam.d/*
509
554
  EOF
510
555
  when /opensuse/, /sles/
511
556
  dockerfile += <<~EOF
512
- RUN zypper -n in openssh #{Beaker::HostPrebuiltSteps::SLES_PACKAGES.join(' ')}
557
+ RUN zypper -n in openssh #{additional_packages.join(' ')}
513
558
  RUN ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key
514
559
  RUN ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key
515
560
  RUN sed -ri 's/^#?UsePAM .*/UsePAM no/' /etc/ssh/sshd_config
@@ -519,7 +564,7 @@ module Beaker
519
564
  dockerfile += <<~EOF
520
565
  RUN pacman --noconfirm -Sy archlinux-keyring
521
566
  RUN pacman --noconfirm -Syu
522
- RUN pacman -S --noconfirm openssh #{Beaker::HostPrebuiltSteps::ARCHLINUX_PACKAGES.join(' ')}
567
+ RUN pacman -S --noconfirm openssh #{additional_packages.join(' ')}
523
568
  RUN ssh-keygen -A
524
569
  RUN sed -ri 's/^#?UsePAM .*/UsePAM no/' /etc/ssh/sshd_config
525
570
  RUN systemctl enable sshd
data/lib/beaker-docker/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module BeakerDocker
2
- VERSION = '0.8.3'
2
+ VERSION = '1.1.0'
3
3
  end
data/spec/beaker/hypervisor/docker_spec.rb CHANGED
@@ -68,7 +68,7 @@ module Beaker
68
68
  'Ports' => {
69
69
  '22/tcp' => [
70
70
  {
71
- 'HostIp' => '127.0.1.1',
71
+ 'HostIp' => '0.0.0.0',
72
72
  'HostPort' => 8022,
73
73
  },
74
74
  ],
@@ -105,6 +105,10 @@ module Beaker
105
105
 
106
106
  let (:version) { {"ApiVersion"=>"1.18", "Arch"=>"amd64", "GitCommit"=>"4749651", "GoVersion"=>"go1.4.2", "KernelVersion"=>"3.16.0-37-generic", "Os"=>"linux", "Version"=>"1.6.0"} }
107
107
 
108
+ before :each do
109
+ allow(::Docker).to receive(:rootless?).and_return(true)
110
+ end
111
+
108
112
  context 'with connection failure' do
109
113
  describe '#initialize' do
110
114
  before :each do
@@ -130,6 +134,7 @@ module Beaker
130
134
  allow( ::Docker ).to receive(:options).and_return(docker_options)
131
135
  allow( ::Docker ).to receive(:options=)
132
136
  allow( ::Docker ).to receive(:logger=)
137
+ allow( ::Docker ).to receive(:podman?).and_return(false)
133
138
  allow( ::Docker ).to receive(:version).and_return(version)
134
139
  allow( ::Docker::Image ).to receive(:build).and_return(image)
135
140
  allow( ::Docker::Image ).to receive(:create).and_return(image)
@@ -471,6 +476,40 @@ module Beaker
471
476
  docker.provision
472
477
  end
473
478
 
479
+ it 'should create a container with port bindings' do
480
+ hosts.each_with_index do |host, index|
481
+ host['docker_port_bindings'] = {
482
+ '8080/tcp' => [{ 'HostPort' => '8080', 'HostIp' => '0.0.0.0'}]
483
+ }
484
+
485
+ expect( ::Docker::Container ).to receive(:create).with({
486
+ 'ExposedPorts' => {
487
+ '8080/tcp' => {},
488
+ },
489
+ 'Image' => image.id,
490
+ 'Hostname' => host.name,
491
+ 'HostConfig' => {
492
+ 'PortBindings' => {
493
+ '22/tcp' => [{ 'HostPort' => /\b\d{4}\b/, 'HostIp' => '0.0.0.0'}],
494
+ '8080/tcp' => [{ 'HostPort' => '8080', 'HostIp' => '0.0.0.0'}]
495
+ },
496
+ 'PublishAllPorts' => true,
497
+ 'Privileged' => true,
498
+ 'RestartPolicy' => {
499
+ 'Name' => 'always'
500
+ },
501
+ },
502
+ 'Labels' => {
503
+ 'one' => (index == 2 ? 3 : 1),
504
+ 'two' => (index == 2 ? 4 : 2),
505
+ },
506
+ 'name' => /\Abeaker-/
507
+ })
508
+ end
509
+
510
+ docker.provision
511
+ end
512
+
474
513
  it 'should start the container' do
475
514
  expect( container ).to receive(:start)
476
515
 
@@ -486,7 +525,7 @@ module Beaker
486
525
  ENV['DOCKER_HOST'] = nil
487
526
  docker.provision
488
527
 
489
- expect( hosts[0]['ip'] ).to be === '127.0.1.1'
528
+ expect( hosts[0]['ip'] ).to be === '127.0.0.1'
490
529
  expect( hosts[0]['port'] ).to be === 8022
491
530
  end
492
531
 
@@ -502,7 +541,7 @@ module Beaker
502
541
  ENV['DOCKER_HOST'] = nil
503
542
  docker.provision
504
543
 
505
- expect( hosts[0]['ip'] ).to be === '127.0.1.1'
544
+ expect( hosts[0]['ip'] ).to be === '127.0.0.1'
506
545
  expect( hosts[0]['port'] ).to be === 8022
507
546
  expect( hosts[0]['ssh'][:password] ).to be === 'root'
508
547
  expect( hosts[0]['ssh'][:port] ).to be === 8022
@@ -532,8 +571,8 @@ module Beaker
532
571
  ENV['DOCKER_HOST'] = nil
533
572
  docker.provision
534
573
 
535
- expect( hosts[0]['ip'] ).to be === '192.0.2.1'
536
- expect( hosts[0]['port'] ).to be === '22'
574
+ expect( hosts[0]['ip'] ).to be === '127.0.0.1'
575
+ expect( hosts[0]['port'] ).to be === 8022
537
576
  end
538
577
  end
539
578
 
@@ -693,7 +732,7 @@ module Beaker
693
732
  expect( dockerfile ).to be =~ /RUN zypper -n in openssh/
694
733
  end
695
734
 
696
- (22..29).to_a.each do | fedora_release |
735
+ (22..39).to_a.each do | fedora_release |
697
736
  it "should use dnf on fedora #{fedora_release}" do
698
737
  FakeFS.deactivate!
699
738
  dockerfile = docker.send(:dockerfile_for, {
data/spec/spec_helper.rb CHANGED
@@ -1,7 +1,30 @@
1
- require 'simplecov'
2
1
  require 'rspec/its'
3
2
  require 'beaker'
4
3
 
4
+ begin
5
+ require 'simplecov'
6
+ require 'simplecov-console'
7
+ require 'codecov'
8
+ rescue LoadError
9
+ else
10
+ SimpleCov.start do
11
+ track_files 'lib/**/*.rb'
12
+
13
+ add_filter '/spec'
14
+
15
+ enable_coverage :branch
16
+
17
+ # do not track vendored files
18
+ add_filter '/vendor'
19
+ add_filter '/.vendor'
20
+ end
21
+
22
+ SimpleCov.formatters = [
23
+ SimpleCov::Formatter::Console,
24
+ SimpleCov::Formatter::Codecov,
25
+ ]
26
+ end
27
+
5
28
  Dir.glob(Dir.pwd + '/lib/beaker/hypervisor/*.rb') {|file| require file}
6
29
 
7
30
  # setup & require beaker's spec_helper.rb
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: beaker-docker
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.8.3
4
+ version: 1.1.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Vox Pupuli
@@ -11,7 +11,7 @@ authors:
11
11
  autorequire:
12
12
  bindir: bin
13
13
  cert_chain: []
14
- date: 2021-02-28 00:00:00.000000000 Z
14
+ date: 2022-01-27 00:00:00.000000000 Z
15
15
  dependencies:
16
16
  - !ruby/object:Gem::Dependency
17
17
  name: rspec
@@ -70,61 +70,47 @@ dependencies:
70
70
  - !ruby/object:Gem::Version
71
71
  version: '13.0'
72
72
  - !ruby/object:Gem::Dependency
73
- name: simplecov
74
- requirement: !ruby/object:Gem::Requirement
75
- requirements:
76
- - - "~>"
77
- - !ruby/object:Gem::Version
78
- version: '0.18'
79
- type: :development
80
- prerelease: false
81
- version_requirements: !ruby/object:Gem::Requirement
82
- requirements:
83
- - - "~>"
84
- - !ruby/object:Gem::Version
85
- version: '0.18'
86
- - !ruby/object:Gem::Dependency
87
- name: pry
73
+ name: stringify-hash
88
74
  requirement: !ruby/object:Gem::Requirement
89
75
  requirements:
90
76
  - - "~>"
91
77
  - !ruby/object:Gem::Version
92
- version: '0.10'
93
- type: :development
78
+ version: 0.0.0
79
+ type: :runtime
94
80
  prerelease: false
95
81
  version_requirements: !ruby/object:Gem::Requirement
96
82
  requirements:
97
83
  - - "~>"
98
84
  - !ruby/object:Gem::Version
99
- version: '0.10'
85
+ version: 0.0.0
100
86
  - !ruby/object:Gem::Dependency
101
- name: stringify-hash
87
+ name: docker-api
102
88
  requirement: !ruby/object:Gem::Requirement
103
89
  requirements:
104
90
  - - "~>"
105
91
  - !ruby/object:Gem::Version
106
- version: 0.0.0
92
+ version: '2.1'
107
93
  type: :runtime
108
94
  prerelease: false
109
95
  version_requirements: !ruby/object:Gem::Requirement
110
96
  requirements:
111
97
  - - "~>"
112
98
  - !ruby/object:Gem::Version
113
- version: 0.0.0
99
+ version: '2.1'
114
100
  - !ruby/object:Gem::Dependency
115
- name: docker-api
101
+ name: beaker
116
102
  requirement: !ruby/object:Gem::Requirement
117
103
  requirements:
118
- - - "<"
104
+ - - ">="
119
105
  - !ruby/object:Gem::Version
120
- version: 3.0.0
106
+ version: '4.34'
121
107
  type: :runtime
122
108
  prerelease: false
123
109
  version_requirements: !ruby/object:Gem::Requirement
124
110
  requirements:
125
- - - "<"
111
+ - - ">="
126
112
  - !ruby/object:Gem::Version
127
- version: 3.0.0
113
+ version: '4.34'
128
114
  description: For use for the Beaker acceptance testing tool
129
115
  email:
130
116
  - voxpupuli@groups.io
@@ -138,6 +124,7 @@ files:
138
124
  - ".github/workflows/test.yml"
139
125
  - ".gitignore"
140
126
  - ".simplecov"
127
+ - CHANGELOG.md
141
128
  - Gemfile
142
129
  - Gemfile.local
143
130
  - LICENSE
@@ -171,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
171
158
  - !ruby/object:Gem::Version
172
159
  version: '0'
173
160
  requirements: []
174
- rubygems_version: 3.1.4
161
+ rubygems_version: 3.2.32
175
162
  signing_key:
176
163
  specification_version: 4
177
164
  summary: Beaker DSL Extension Helpers!