cookbooks/apt_utils/README.md

   1 apt_utils Cookbook
   2 ==================
   3
   4 This cookbook includes apt utility (apt-cacher-ng, apt mirroring site setup and apt source configuration) recipes.
   5
   6 ## Contents
   7
   8 - [Requirements](#requirements)
   9     - [packages](#packages)
  10 - [Attributes](#attributes)
  11     - [apt_utils::default](#apt_utilsdefault)
  12 - [Usage](#usage)
  13     - [Recipes](#recipes)
  14         - [apt_utils::apt](#apt_utilsapt)
  15         - [apt_utils::aptly](#apt_utilsaptly)
  16         - [apt_utils::aptly-docker-compose](#apt_utilsaptly-docker-compose)
  17             - [SSL server keys and certificates management by the `ssl_cert` cookbook](#ssl-server-keys-and-certificates-management-by-the-ssl_cert-cookbook)
  18         - [apt_utils::conf](#apt_utilsconf)
  19         - [apt_utils::apt-cacher-ng](#apt_utilsapt-cacher-ng)
  20         - [apt_utils::mirror](#apt_utilsmirror)
  21         - [apt_utils::source](#apt_utilssource)
  22 - [License and Authors](#license-and-authors)
  23
  24 ## Requirements
  25
  26 ### packages
  27
  28 - `apt`
  29 - `docker-grid` >= 0.2.7
  30 - `platform_utils` >= 0.4.3
  31 - `ssl_cert` >= 0.3.7
  32
  33
  34 ## Attributes
  35
  36 ### apt_utils::default
  37
  38 |Key|Type|Description (with examples)|Default|
  39 |:--|:--|:--|:--|
  40 |`['apt_utils']['conf']['proxy']['sequence']`|String|Sequence number of apt proxy configuration file (ver. 0.1.1 or later)|`'80'`|
  41 |`['apt_utils']['conf']['proxy']['ftp']`|String|Proxy setting for FTP (ver. 0.1.1 or later)|`'nil'`|
  42 |`['apt_utils']['conf']['proxy']['http']`|String|Proxy setting for HTTP (ver. 0.1.1 or later)|`'nil'`|
  43 |`['apt_utils']['conf']['proxy']['https']`|String|Proxy setting for HTTPS (ver. 0.1.1 or later)|`'nil'`|
  44 |`['apt_utils']['aptly']['apt_repo']['keyserver']`|String||`'keys.gnupg.net'`|
  45 |`['apt_utils']['aptly']['apt_repo']['recv-keys']`|String||`'9E3E53F19C7DE460'`|
  46 |`['apt_utils']['aptly']['user']`|String||`'root'`|
  47 |`['apt_utils']['aptly']['conf']`|Hash|`aptly.conf` configurations.|See `attributes/default.rb`|
  48 |`['apt_utils']['aptly']['with_ssl_cert_cookbook']`|Boolean|Activates TLS configurations by the `ssl_cert` cookbook. See `attributes/default.rb`|`false`|
  49 |`['apt_utils']['aptly']['ssl_cert']['common_name']`|String|Server common name for TLS|`node['fqdn']`|
  50 |`['apt_utils']['aptly']['docker-compose']['app_dir']`|String|aptly app. root directory for docker-compose.|`"#{node['docker-grid']['compose']['app_dir']}/aptly"`|
  51 |`['apt_utils']['aptly']['docker-compose']['etc_dir']`|String||`"#{node['apt_utils']['aptly']['docker-compose']['app_dir']}/etc"`|
  52 |`['apt_utils']['aptly']['docker-compose']['data_dir']`|String|Persistent volume path or nil (unset).|`"#{node['apt_utils']['aptly']['docker-compose']['app_dir']}/data"`|
  53 |`['apt_utils']['aptly']['docker-compose']['config']`|Hash|`docker-compose.yml` configurations.|See `attributes/default.rb`|
  54 |`['apt_utils']['apt-cacher-ng']['CacheDir']`|String|path to cache directory|`'/var/cache/apt-cacher-ng'`|
  55 |`['apt_utils']['apt-cacher-ng']['LogDir']`|String|path to log directory.|`'/var/log/apt-cacher-ng'`|
  56 |`['apt_utils']['apt-cacher-ng']['Port']`|String|service port number.|`'3142'`|
  57 |`['apt_utils']['apt-cacher-ng']['BindAddress']`|String|service bind address|`''` (0.0.0.0)|
  58 |`['apt_utils']['apt-cacher-ng']['UseWrap']`|String|with TCP Wrappers (ver. 0.1.2 or later)|`nil` (`'0'`(default) or `'1'` (on))|
  59 |`['apt_utils']['mirror']['user']`|String|service user.|`'apt-mirror'`|
  60 |`['apt_utils']['mirror']['cron_period']`|String|cron period expression.|`'#0 4   * * *'` (inactive)|
  61 |`['apt_utils']['mirror']['base_path']`|String|mirroring base path.|`'/var/spool/apt-mirror'`|
  62 |`['apt_utils']['mirror']['nthreads']`|String|worker threads number.|`'20'`|
  63 |`['apt_utils']['mirror']['_tilde']`|||`'0'`|
  64 |`['apt_utils']['mirror']['country']`|String|mirroring source country.|`'us'`|
  65 |`['apt_utils']['mirror']['distributions']['debian']`|Hash|Debian's mirroring apt lines.|refer to `attributes/default.rb`|
  66 |`['apt_utils']['mirror']['distributions']['ubuntu']`|Hash|Ubuntu's mirroring apt lines.|refer to `attributes/default.rb`|
  67 |`['apt_utils']['source']['apt_lines']['ubuntu']`|Array|apt source lines.|refer to `attributes/default.rb`|
  68
  69 ## Usage
  70
  71 ### Recipes
  72
  73 #### apt_utils::apt
  74
  75 - includes `apt::default` recipe if the platform family is `debian`.
  76
  77 #### apt_utils::aptly
  78
  79 This recipe installs `aptly` package.
  80
  81 - `roles/aptly.rb`: role example.
  82
  83 ```ruby
  84 name 'aptly'
  85 description 'aptly'
  86
  87 run_list(
  88   'recipe[apt_utils::aptly]',
  89 )
  90 ```
  91
  92 #### apt_utils::aptly-docker-compose
  93
  94 This recipe generates a `docker-compose.yml` file for the aptly service.
  95
  96 - `roles/aptly-docker-compose.rb`: role example.
  97
  98 ```ruby
  99 name 'aptly-docker-compose'
 100 description 'aptly by docker-compose'
 101
 102 run_list(
 103   'role[docker]',
 104   'recipe[apt_utils::aptly-docker-compose]',
 105 )
 106
 107 aptly_port = '8080'
 108 aptly_api_port = '8081'
 109
 110 override_attributes(
 111   'apt_utils' => {
 112     'aptly' => {
 113       'docker-compose' => {
 114         'config' => {
 115           'version' => '2',
 116           'services' => {
 117             'reverseproxy' => {
 118               'ports' => [
 119                 "#{aptly_port}:8080",
 120                 "#{aptly_api_port}:8081",
 121               ],
 122               'volumes' => [
 123                 # This volume will be set by the apt_utils::aptly-docker-compose recipe automatically.
 124                 #"#{node['apt_utils']['aptly']['docker-compose']['etc_dir']}/nginx/nginx.conf:/etc/nginx/nginx.conf:ro"
 125               ],
 126             },
 127             'aptly' => {
 128               'restart' => 'always',
 129               'image' => 'whitestar/aptly',
 130               'volumes' => [
 131                 # This volume will be set by the apt_utils::aptly-docker-compose recipe automatically.
 132                 #"#{node['apt_utils']['aptly']['docker-compose']['data_dir']}:/aptly-data:rw",
 133               ],
 134               'environment' => {
 135               },
 136             },
 137           },
 138         },
 139       },
 140     },
 141   },
 142 )
 143 ```
 144
 145 - `roles/aptly-with-ssl-docker-compose.rb`: SSL setup role example.
 146
 147 ```ruby
 148 name 'aptly-with-ssl-docker-compose'
 149 description 'aptly with SSL by docker-compose'
 150
 151 run_list(
 152   #'recipe[ssl_cert::server_key_pairs]',  # apt_utils cookbook < 0.2.4
 153   'role[docker]',
 154   'recipe[apt_utils::aptly-docker-compose]',
 155 )
 156
 157 aptly_port = '8080'
 158 aptly_api_port = '8081'
 159 cn = 'aptly.io.example.com'
 160
 161 override_attributes(
 162   'ssl_cert' => {
 163     #'common_names' => [
 164     #  cn,  # apt_utils cookbook <= 0.2.6
 165     #],
 166   },
 167   'apt_utils' => {
 168     'aptly' => {
 169       'with_ssl_cert_cookbook' => true,
 170       'ssl_cert' => {
 171         'common_name' => cn,
 172       },
 173       'docker-compose' => {
 174         'config' => {
 175           'version' => '2',
 176           'services' => {
 177             'reverseproxy' => {
 178               'ports' => [
 179                 "#{aptly_port}:8080",
 180                 "#{aptly_api_port}:8081",
 181               ],
 182               'volumes' => [
 183                 # These volumes will be set by the apt_utils::aptly-docker-compose recipe automatically.
 184                 #"#{node['apt_utils']['aptly']['docker-compose']['etc_dir']}/nginx/nginx.conf:/etc/nginx/nginx.conf:ro"
 185                 # and server key pair volume conf.
 186               ],
 187             },
 188             'aptly' => {
 189               'restart' => 'always',
 190               'image' => 'whitestar/aptly',
 191               'volumes' => [
 192                 # This volume will be set by the apt_utils::aptly-docker-compose recipe automatically.
 193                 #"#{node['apt_utils']['aptly']['docker-compose']['data_dir']}:/aptly-data:rw",
 194               ],
 195               'environment' => {
 196               },
 197             },
 198           },
 199         },
 200       },
 201     },
 202   },
 203 )
 204 ```
 205
 206 ##### SSL server keys and certificates management by the `ssl_cert` cookbook
 207
 208 - create vault items.
 209
 210 ```text
 211 $ ruby -rjson -e 'puts JSON.generate({"private" => File.read("aptly.io.example.com.prod.key")})' \
 212 > > ~/tmp/aptly.io.example.com.prod.key.json
 213
 214 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("aptly.io.example.com.prod.crt")})' \
 215 > > ~/tmp/aptly.io.example.com.prod.crt.json
 216
 217 $ cd $CHEF_REPO_PATH
 218
 219 $ knife vault create ssl_server_keys aptly.io.example.com.prod \
 220 > --json ~/tmp/aptly.io.example.com.prod.key.json
 221
 222 $ knife vault create ssl_server_certs aptly.io.example.com.prod \
 223 > --json ~/tmp/aptly.io.example.com.prod.crt.json
 224 ```
 225
 226 - grant reference permission to the Concourse host
 227
 228 ```text
 229 $ knife vault update ssl_server_keys  aptly.io.example.com.prod -S 'name:aptly-host.example.com'
 230 $ knife vault update ssl_server_certs aptly.io.example.com.prod -S 'name:aptly-host.example.com'
 231 ```
 232
 233 - modify run_list and attributes
 234
 235 ```ruby
 236 run_list(
 237   #'recipe[ssl_cert::server_key_pairs]',  # apt_utils cookbook < 0.2.4
 238   'recipe[apt_utils::aptly-docker-compose]',
 239 )
 240
 241 override_attributes(
 242   'ssl_cert' => {
 243     #'common_names' => [
 244     #  'aptly.io.example.com',  # apt_utils cookbook < 0.2.6
 245     #],
 246   },
 247   'aptly-grid' => {
 248     'with_ssl_cert_cookbook' => true,
 249     'ssl_cert' => {
 250       'common_name' => 'nexus.io.example.com',
 251     },
 252     # ...
 253   },
 254 )
 255 ```
 256
 257 #### apt_utils::conf
 258
 259 - deploys apt configuration files to the `/etc/apt/apt.conf.d` directory.
 260
 261 #### apt_utils::apt-cacher-ng
 262
 263 ```json
 264 {
 265   "name":"my_node",
 266   "run_list": [
 267     "recipe[apt_utils::apt-cacher-ng]"
 268   ]
 269 }
 270 ```
 271
 272 #### apt_utils::mirror
 273
 274 ```json
 275 {
 276   "name":"my_node",
 277   "run_list": [
 278     "recipe[apt_utils::mirror]"
 279   ]
 280 }
 281 ```
 282
 283 #### apt_utils::source
 284
 285 ```json
 286 {
 287   "name":"my_node",
 288   "run_list": [
 289     "recipe[apt_utils::source]"
 290   ]
 291 }
 292 ```
 293
 294 ## License and Authors
 295
 296 - Author:: whitestar at osdn.jp
 297
 298 ```text
 299 Copyright 2013-2017, whitestar
 300
 301 Licensed under the Apache License, Version 2.0 (the "License");
 302 you may not use this file except in compliance with the License.
 303 You may obtain a copy of the License at
 304
 305     http://www.apache.org/licenses/LICENSE-2.0
 306
 307 Unless required by applicable law or agreed to in writing, software
 308 distributed under the License is distributed on an "AS IS" BASIS,
 309 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 310 See the License for the specific language governing permissions and
 311 limitations under the License.
 312 ```