imip-agent

Annotated docs/wiki/GettingStarted

1021:a04c967b2d8e
2015-11-06 Paul Boddie Removed the complicated "old" lock directory mechanism since the active lock directory should be protected by the "outside-in" attempts to create it while the dismantling operation occurs "inside-out".
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@955 32
== Installing the Software ==
paul@955 33
paul@955 34
Ideally, an operating system distribution package should be used to
paul@955 35
install the software. As a result, the software should already be suitably
paul@955 36
integrated and configured and guidance will be available to get everything
paul@955 37
working.
paul@955 38
paul@955 39
 1. In the absence of a suitable system package, the installation locations
paul@955 40
 and system user details must first be configured, as described above.
paul@955 41
paul@955 42
 1. Then, the `tools/install.sh` script should install the software in
paul@955 43
 appropriate locations. You may need to be `root` or use `sudo` to
paul@955 44
 successfully use this script.
paul@955 45
paul@961 46
{{{
paul@961 47
tools/install.sh
paul@961 48
}}}
paul@961 49
paul@955 50
See the [[../Prerequisites|prerequisites]] for other software that will be
paul@955 51
required for the software to function. 
paul@955 52
paul@955 53
== Initialising the Software ==
paul@955 54
paul@955 55
Once a suitable system user has been chosen, stored and published data is then
paul@955 56
initialised using the `tools/init.sh` script. The script employs the setgid
paul@955 57
flag on the directories initialised for stored and published data so that new
paul@955 58
files and directories have the appropriate group associated with them.
paul@955 59
paul@955 60
It should be possible to omit all arguments to the `init.sh` script, but it is
paul@955 61
also worth reading the help message:
paul@955 62
paul@955 63
{{{
paul@955 64
tools/init.sh --help
paul@955 65
}}}
paul@955 66
paul@1006 67
Fixing ownership can be done using the `tools/fix.sh` script, as described in
paul@1006 68
the [[../Administration|administration guide]] in case some form of modification
paul@1006 69
has altered the ownership or membership of the created files and directories.
paul@955 70
paul@1006 71
== Integrating with Other Software ==
paul@955 72
paul@1006 73
The `conf` directory in the imip-agent source code distribution contains
paul@1006 74
subdirectories for different systems:
paul@955 75
paul@961 76
{{{#!table
paul@961 77
'''Directory''' || '''Description''' || '''Guide'''
paul@961 78
==
paul@961 79
`apache`
paul@961 80
|| Apache 2 site configuration for publishing resources
paul@961 81
|| [[../WebServerIntegration|Web Server Integration]]
paul@961 82
==
paul@961 83
`cron`
paul@961 84
|| Cron command scheduling for free/busy updates
paul@961 85
|| [[../CronIntegration|Cron Task Scheduler Integration]]
paul@961 86
==
paul@961 87
`exim`
paul@961 88
|| Exim 4 routing and transport configuration
paul@988 89
|| [[../MailIntegration|E-Mail Integration]] and
paul@988 90
.. [[../MailboxIntegration|Mailbox Integration]]
paul@961 91
==
paul@961 92
`ldap`
paul@961 93
|| Some LDAP-related resources
paul@961 94
||
paul@961 95
==
paul@961 96
`postfix`
paul@961 97
|| Postfix routing and transport configuration
paul@988 98
|| [[../MailIntegration|E-Mail Integration]] and
paul@988 99
.. [[../MailboxIntegration|Mailbox Integration]]
paul@961 100
}}}
paul@955 101
paul@961 102
== Configuring the Software ==
paul@955 103
paul@961 104
The behaviour of the imip-agent software itself can be configured using
paul@961 105
mechanisms described in the [[../Configuration|configuration guide]].
paul@988 106
paul@1006 107
== Administering the Software ==
paul@1006 108
paul@1006 109
With the basic configuration performed, all that remains is to perform
paul@1006 110
any necessary [[../Administration|administration tasks]] to set the
paul@1006 111
software up for certain kinds of users or participants.
paul@1006 112
paul@988 113
== Using the Software ==
paul@988 114
paul@1006 115
With configuration and administration performed, it should be possible
paul@1006 116
to get started using the software. See the [[../Usage|usage guide]]
paul@1006 117
for details.