imip-agent

Annotated docs/wiki/GettingStarted

1384:9baa0aae5b43
1113:cfbb32370151
2017-10-31 Paul Boddie file changeset files shortlog Provided a convenience function for instantiating handler objects. Added a mode that produces output instead of sending messages without also producing debugging information. client-editing-simplification
paul@955 1 
= Getting Started =
paul@955 2 
 
 paul@955      3 
To get imip-agent running on your own system you will need the following:
 
 paul@955      4 
 
 paul@955      5 
 * The ability to install software and to configure the system
 
 paul@955      6 
 * A working mail configuration
 
 paul@955      7 
 
 paul@955      8 
It is possible to [[../Testing|test the agent programs]] without these
 
 paul@955      9 
abilities, but any difficulties in getting the software to work will be
 
 paul@955     10 
compounded by any problem or deficiency in either of these areas.
 
 paul@955     11 
 
 paul@1006     12 
<<TableOfContents(2,2)>>
 
 paul@1006     13 
 
 paul@1006     14 
== Obtaining the Software ==
 
 paul@1006     15 
 
 paul@1006     16 
To get started, the imip-agent software must be [[../Downloads|downloaded]]
 
 paul@1006     17 
and any [[../Prerequisites|prerequisites]] installed, the latter being
 
 paul@1006     18 
software that imip-agent needs to work with. The choice of prerequisites
 
 paul@1006     19 
will influence some of the activities described below.
 
 paul@1006     20 
 
 paul@955     21 
== Configuring System Users ==
 
 paul@955     22 
 
 paul@955     23 
The [[../SystemUsers|system users guide]] indicates the requirements for
 
 paul@955     24 
system user and group configuration.
 
 paul@955     25 
 
 paul@955     26 
If you are comfortable configuring your mail system, you may decide to
 
 paul@955     27 
choose the [[../MailIntegration/LocalSMTP|local SMTP delivery]] approach.
 
 paul@955     28 
 
 paul@955     29 
If you already use mail storage solutions that employ LMTP, you may decide
 
 paul@955     30 
to choose the [[../MailIntegration/LMTP|LMTP delivery]] approach.
 
 paul@955     31 
 
 paul@1112     32 
Once you have decided which approach is the most preferable, you will be
 
 paul@1112     33 
able to use this choice to influence the configuration process mentioned
 
 paul@1112     34 
below.
 
 paul@1112     35 
 
 paul@955     36 
== Installing the Software ==
 
 paul@955     37 
 
 paul@955     38 
Ideally, an operating system distribution package should be used to
 
 paul@955     39 
install the software. As a result, the software should already be suitably
 
 paul@955     40 
integrated and configured and guidance will be available to get everything
 
 paul@955     41 
working.
 
 paul@955     42 
 
 paul@955     43 
 1. In the absence of a suitable system package, the installation locations
 
 paul@955     44 
 and system user details must first be configured, as described above.
 
 paul@955     45 
 
 paul@955     46 
 1. Then, the `tools/install.sh` script should install the software in
 
 paul@955     47 
 appropriate locations. You may need to be `root` or use `sudo` to
 
 paul@955     48 
 successfully use this script.
 
 paul@955     49 
 
 paul@961     50 
{{{
 
 paul@961     51 
tools/install.sh
 
 paul@961     52 
}}}
 
 paul@961     53 
 
 paul@955     54 
See the [[../Prerequisites|prerequisites]] for other software that will be
 
 paul@955     55 
required for the software to function. 
 
 paul@955     56 
 
 paul@955     57 
== Initialising the Software ==
 
 paul@955     58 
 
 paul@955     59 
Once a suitable system user has been chosen, stored and published data is then
 
 paul@955     60 
initialised using the `tools/init.sh` script. The script employs the setgid
 
 paul@955     61 
flag on the directories initialised for stored and published data so that new
 
 paul@955     62 
files and directories have the appropriate group associated with them.
 
 paul@955     63 
 
 paul@955     64 
It should be possible to omit all arguments to the `init.sh` script, but it is
 
 paul@955     65 
also worth reading the help message:
 
 paul@955     66 
 
 paul@955     67 
{{{
 
 paul@955     68 
tools/init.sh --help
 
 paul@955     69 
}}}
 
 paul@955     70 
 
 paul@1006     71 
Fixing ownership can be done using the `tools/fix.sh` script, as described in
 
 paul@1006     72 
the [[../Administration|administration guide]] in case some form of modification
 
 paul@1006     73 
has altered the ownership or membership of the created files and directories.
 
 paul@955     74 
 
 paul@1006     75 
== Integrating with Other Software ==
 
 paul@955     76 
 
 paul@1006     77 
The `conf` directory in the imip-agent source code distribution contains
 
 paul@1006     78 
subdirectories for different systems:
 
 paul@955     79 
 
 paul@961     80 
{{{#!table
 
 paul@961     81 
'''Directory''' || '''Description''' || '''Guide'''
 
 paul@961     82 
==
 
 paul@961     83 
`apache`
 
 paul@961     84 
|| Apache 2 site configuration for publishing resources
 
 paul@961     85 
|| [[../WebServerIntegration|Web Server Integration]]
 
 paul@961     86 
==
 
 paul@961     87 
`cron`
 
 paul@961     88 
|| Cron command scheduling for free/busy updates
 
 paul@961     89 
|| [[../CronIntegration|Cron Task Scheduler Integration]]
 
 paul@961     90 
==
 
 paul@961     91 
`exim`
 
 paul@961     92 
|| Exim 4 routing and transport configuration
 
 paul@988     93 
|| [[../MailIntegration|E-Mail Integration]] and
 
 paul@988     94 
.. [[../MailboxIntegration|Mailbox Integration]]
 
 paul@961     95 
==
 
 paul@961     96 
`ldap`
 
 paul@961     97 
|| Some LDAP-related resources
 
 paul@961     98 
||
 
 paul@961     99 
==
 
 paul@961    100 
`postfix`
 
 paul@961    101 
|| Postfix routing and transport configuration
 
 paul@988    102 
|| [[../MailIntegration|E-Mail Integration]] and
 
 paul@988    103 
.. [[../MailboxIntegration|Mailbox Integration]]
 
 paul@1089    104 
==
 
 paul@1089    105 
`postgresql`
 
 paul@1089    106 
|| PostgreSQL configuration
 
 paul@1089    107 
|| [[../DatabaseStore|Database Store]]
 
 paul@961    108 
}}}
 
 paul@955    109 
 
 paul@1112    110 
In addition, a `tools` directory provides a configuration helper tool
 
 paul@1112    111 
that can be used to quickly customise the above resources and produce
 
 paul@1112    112 
files that, after review, may be deployed.
 
 paul@1112    113 
 
 paul@1112    114 
{{{
 
 paul@1112    115 
conf/tools/configure.sh --help
 
 paul@1112    116 
}}}
 
 paul@1112    117 
 
 paul@1112    118 
Use of this tool is covered in the [[../Configuration|configuration guide]].
 
 paul@1112    119 
 
 paul@961    120 
== Configuring the Software ==
 
 paul@955    121 
 
 paul@961    122 
The behaviour of the imip-agent software itself can be configured using
 
 paul@961    123 
mechanisms described in the [[../Configuration|configuration guide]].
 
 paul@988    124 
 
 paul@1006    125 
== Administering the Software ==
 
 paul@1006    126 
 
 paul@1006    127 
With the basic configuration performed, all that remains is to perform
 
 paul@1006    128 
any necessary [[../Administration|administration tasks]] to set the
 
 paul@1006    129 
software up for certain kinds of users or participants.
 
 paul@1006    130 
 
 paul@988    131 
== Using the Software ==
 
 paul@988    132 
 
 paul@1006    133 
With configuration and administration performed, it should be possible
 
 paul@1006    134 
to get started using the software. See the [[../Usage|usage guide]]
 
 paul@1006    135 
for details.