doc/getting_started.md

   1 # Getting Started with Dinit
   2
   3 In this guide we will go through the steps required to set up a tiny user-mode
   4 dinit instance.
   5
   6 We assume that dinit has already been installed; i.e. we only cover
   7 configuration here.
   8
   9 ## Starting Dinit
  10
  11 Let's start by running dinit with the bare minimum configuration. First we need
  12 to choose a place for our service descriptions to live. For this guide we are
  13 going to use the default location (for user-mode), which is `~/dinit.d`.
  14
  15 ```
  16 $ mkdir ~/dinit.d
  17 $ cd ~/dinit.d
  18 ```
  19
  20 Next we need a service description for the `boot` service. This is the service
  21 that dinit will bring up upon starting.
  22
  23 In a file called `boot` (under the directory we just made) put:
  24 ```
  25 type = internal
  26 waits-for.d = boot.d
  27 ```
  28
  29 The first line tells dinit that this is not a service which will run anything
  30 directly.
  31
  32 The second line specifies a directory which will be used to keep track of which
  33 services should be enabled at dinit start time. Here we've made it a `boot.d`
  34 sub-directory under our main dinit directory, but it can be anywhere you like.
  35
  36 Now let's make the aforementioned directory and start dinit for the first time.
  37 Assuming you are still in `~/dinit.d`:
  38
  39 ```
  40 $ mkdir boot.d
  41 $ dinit -d .
  42 [  OK  ] boot
  43 ```
  44
  45 Dinit lives!
  46
  47 In the long run, you'll want to find a way to invoke dinit at boot time, but
  48 that's an exercise for the reader.
  49
  50 ## Adding Service Descriptions
  51
  52 So we have dinit running, but it currently has no services to supervise. Let's
  53 give it something to do.
  54
  55 Suppose we want to run mpd under dinit. Put the following in ` ~/dinit.d/mpd`:
  56 ```
  57 type = process
  58 command = /usr/local/sbin/mpd --no-daemon
  59 restart = true
  60 ```
  61
  62 Now run `dinitctl list`:
  63 ```
  64 $ dinitctl list
  65 [{+}     ] boot
  66 ```
  67
  68 The mpd service isn't visible yet because dinit lazily loads services. If we
  69 start the service, we will see it in the list:
  70 ```
  71 $ dinitctl start mpd
  72 Service started.
  73 $ dinitctl list
  74 [{+}     ] boot
  75 [{+}     ] mpd (pid: 14823)
  76 ```
  77
  78 Now let's simulate mpd crashing and check dinit brings it back up:
  79 ```
  80 $ kill 14823
  81 ```
  82
  83 On the dinit log, we see:
  84 ```
  85 [STOPPD] mpd
  86 [  OK  ] mpd
  87 ```
  88
  89 And if we query dinit for its status, we see:
  90 ```
  91 $ dinitctl list
  92 [{+}     ] boot
  93 [{+}     ] mpd (pid: 1667)
  94 ```
  95
  96 Notice that a new instance of mpd is running; it has a different pid.
  97
  98 You can stop a service using `dinitctl stop`:
  99 ```
 100 $ dinitctl list
 101 [{+}     ] boot
 102 [     {-}] mpd
 103 ```
 104
 105 Here the "slider" for the mpd service has been moved to the right to signify
 106 that it has been switched off.
 107
 108 ## Starting Services at Startup
 109
 110 So far we've configured a service which can be brought up and down in an ad-hoc
 111 fashion. This would be ideal for (for example) SSH tunnels, but mpd is the kind
 112 of daemon you want to *always* run.
 113
 114 To that end, to start a service at the time dinit starts, we can use `dinitctl
 115 enable`. This will start the service immediately *and* make sure it starts by
 116 default:
 117 ```
 118 $ dinitctl list
 119 [{+}     ] boot
 120 $ dinitctl enable mpd
 121 $ dinitctl list
 122 [{+}     ] boot
 123 [{+}     ] mpd (pid: 49921)
 124 ```
 125
 126 If we now restart dinit:
 127 ```
 128 $ dinitctl list
 129 [{+}     ] boot
 130 [{+}     ] mpd (pid: 17601)
 131 ```
 132
 133 mpd was started when dinit started.
 134
 135 And if you look in the `waits-for.d` directory we configured earlier you will
 136 find a symlink to the mpd service description file. This is how dinit keeps
 137 track of what should be started by default.
 138
 139 ## Further Reading
 140
 141 In this guide, we've really only scratched the surface of what dinit can do.
 142 For example, we've not even touched on dependencies (where one service depends
 143 upon another to function). Next it'd be good to read the `dinit-service(5)` and
 144 `dinitctl(8)` manual pages.