fork 0k-charms
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

140 lines
4.8 KiB

  1. * 0k-charms
  2. This package provides charms, which are special system recipes, that are
  3. meant to be executable and mangled together to allow managing a wide set
  4. of services.
  5. Inspired by [[https://discourse.juju.is/t/introduction-to-juju-charms/1188][juju charms]], these are mostly bash scripts organized by
  6. service and meant to automate all administration tasks, from
  7. installation, to connection with other services, or any other task a
  8. service would need.
  9. Several tools are able to read the current state of this repository to
  10. effectively deploy full production grade services on different type of
  11. platform.
  12. The only real fully functional implementation is =0k-compose=. It will
  13. use these charms to drive, prepare, and build in =docker=, complete sets
  14. of services.
  15. Another old solution called =lxc-deploy= was used actively before to deploy
  16. services on LXC tool set until 2016 using these charms.
  17. Bare hosts can also replay some recipes to install services directly
  18. on them via the =0k-charm= project using the =charm apply=
  19. command. Note that actually, as most recipes are bash executable, it
  20. is still a viable option to copy-paste parts of source-code of these
  21. scripts. These last two options are still used very often to bootstrap
  22. installs of =docker-hosts= for instance.
  23. * Maturity
  24. Charms in these repository are in a wide set of maturity, from simple note
  25. taking of shell commands, not even executable, to full charm allowing to
  26. deploy services and manage the full life cycle of the service.
  27. The repository in a whole is thus NOT considered as mature at all, and will
  28. require some thorough cleaning and decisions to furthermore structure to reach
  29. a state where it'll make sense to go full public.
  30. * Usage
  31. ** TODO Through =compose= for full deployment of sets of services
  32. Requires =0k-compose= package that contains the =compose= command line tool.
  33. TBD
  34. ** TODO Through =lxc-deploy= for full install and deployment of services
  35. Requires =lxc-scripts= package that holds several tools for LXC
  36. management, amongst them is =lxc-deploy=.
  37. TBD
  38. ** TODO Through =docker-build-charm= for docker image creation
  39. Requires =0k-docker= package that holds several tools for docker
  40. management, amongst them is =docker-build-charm=.
  41. =docker-build-charm= will use the =install= recipes in a charm to
  42. basically mimic the =Dockerfile= purpose and create a docker image for
  43. a specific service.
  44. TBD
  45. ** TODO Through =0k-charm= for bare hosts installs
  46. Requires =0k-charm= package to get the =charm= command line util.
  47. TBD
  48. * Installation
  49. Most tools should check the =CHARM_STORE= bash environment variable
  50. that should be the path to reach the root of this repository. If not
  51. defined, most tools will look in =/srv/charm-store= by default.
  52. * Specs
  53. ** charm type
  54. Not all charm are intended to bring up services as having a container
  55. always running and listening.
  56. In ~metadata.yml~, the root level ~type~ can be one of:
  57. - ~service~ (default)
  58. If not specified, this is the default. A charm brings up a service.
  59. It is meant to be *always running*. For instance, ~apache~, ~mysql~,
  60. ~postgres~ are services.
  61. They usually open ports and are listening to provide their service,
  62. or carry background listening of other ressources (like checking
  63. time and sending scheduling command for the ~cron~ services), and or
  64. use files to trigger or report on their activity.
  65. It will have an entry in the final ~docker-compose.yml~, and thus, a
  66. container will run and stay in memory and have a ~restart:
  67. unless-stopped~ policy. They use CPU and memory ressources.
  68. - ~run-once~
  69. The entry is meant to describe *a command that run once*,
  70. it will be called by a service and *will exit after execution*.
  71. For instance, ~logrotate~, ~rsync-backup~, or ~letsencrypt~ are
  72. of type ~run-once~.
  73. They are meant to be run by service for specific events. They
  74. usually will use relations to ensure they are called at specific
  75. moment by service...
  76. A command does not have an automatic ~restart~ policy as services
  77. have.
  78. They use CPU and memory ressources only when run and gives them back
  79. once finished.
  80. - ~stub~
  81. The entry describes an entity that will *not be run at all*. It is
  82. used to hold information in the ~compose.yml~ and often to *stand
  83. for* a real service managed outside of ~compose.yml~ (on an other
  84. host or on a different managing system, like a local installation or
  85. LXC, virtualbox, ...).
  86. For instance, ~stmp-stub~ can be used to stand for an external ~smtp~.
  87. It is through their relation that they shine as they can provide
  88. similar interface than actual services would have
  89. provided. ~smtp-stub~ is a ~smtp-server~ provider and other charm
  90. can connect to it.
  91. They usually implement relation hooks, and are providers.
  92. No entry will be created in the final ~docker-compose.yml~.
  93. They use no CPU or memory ressources at all.