~evilham/cdist-evilham

cdist-evilham/type/__evilham_dolibarr/man.rst -rw-r--r-- 6.2 KiB
fc863a47 — pedro [__evilham_discourse] update to 2.7.4 6 days ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
cdist-type__evilham_dolibarr(7)
====================================

NAME
----
cdist-type__evilham_dolibarr - Setup Dolibarr ERP/CRM


DESCRIPTION
-----------

This (singleton) type sets up Dolibarr, an ERP/CRM for associations,
free-lancers and big and small companies.

Currently only FreeBSD has been tested and is supported, support for other
Operating Systems might be simple and can be patched on demand.


Note on `--force-sender-hack` and `--force-bcc-hack`:

As of Dolibarr 13.0.1, it assumes that the configured SMTP authentication
details can forge emails for any user; in reality this is rarely the case
and a much more sensible approach based on `Reply-To` headers is not easily
supported.

Furthermore, in our tests, the global BCC setting seemed to have issues.

What these options achieve is:
`--force-sender-hack` uses a single address (probably same one as the one set
up in SMTP) as a sender, and use Dolibarr's original `From` address for the
`Reply-To` header, which is mostly transparent for recipients.
`--force-bcc-hack` allows you to specify an email address that should always
receive a copy of any emails sent by Dolibarr.

These options *patch* Dolibarr's code, which means it is a quirky, bound to
be overwritten, workaround and if you benefit from these, you should look into
improving the hacks and upstreaming the changes.

Note on security:

After running this type for the first time, your `data-root` directory is
probably empty and you need to finish the web configuration.
After doing so, remember to create a file `install.lock` in the `data-root`
directory in a way that Dolibarr can't change it. This will ensure that the
installer / setup code cannot be used.


REQUIRED PARAMETERS
-------------------
database-host
    The hostname where the database is found.
    Remember it must allow connections to that database from this host.

database-user
    The user allowed to access the Dolibarr database.

database-pass
    The password for the user allowed to access the Dolibarr database.

unique-id
    This is usually generated by Dolibarr when it gets configured, however
    we are provisioning the configuration file and it does not have permissions
    to modify it, so we have to set it up.
    This parameter should be considered somewhat secret and should be unique
    and should not change pointlessly for a given instance.
    It should be a 32-char long hex string (digits: `0-9` and `a-f`).
    You can generate one with: `openssl rand -hex 16`
    (16 bytes are 32-hex chars).


OPTIONAL PARAMETERS
-------------------
custom-options
    If you want to override any of the default options or add an option that
    does not have a parameter (like LDAP settings), you can use this.
    If `-`, the type's standard input will be used, else the value passed
    will be added verbatim at the end of the configuration file.

data-root
    The path where Dolibarr will save its documents.
    It MUST be outside of Dolibarr's htdoc directory.
    This directory and the database are what you have to backup.
    Defaults to `/usr/local/www/dolibarr/documents`.

database-name
    The name of the database used for Dolibarr. Defaults to `dolibarr`.

database-port
    The port where the database on `database-host` is listening.
    Defaults to `5432`.

database-type
    The type of database running on `database-host`.
    Defaults to `pgsql`.

force-sender-hack
    The email address used to send all emails from.

force-bcc-hack
    One or multiple comma-separated email addresses to use as BCC for all
    emails.
    See the description for more information.

url
    The main URL that will be used for Dolibarr.
    Defaults to `https://${__target_host}`.


OPTIONAL MULTIPLE PARAMETERS
----------------------------
php-packages
    Any extra PHP packages that you wish to install.
    Good examples of this are `ldap` and ` openssl`.
    Can be either specified multiple times or once separated by spaces.



EXAMPLES
--------

.. code-block:: sh

    # Full example of a Dolibarr instance with LDAP login,
    # Let's Encrypt certificates and Nginx
    #
    # Proceed sequentially
    export CDIST_ORDER_DEPENDENCY=1
    # Setup nginx with support for Let's Encrypt
    __evilham_nginx_server
    # Setup the necessary bits for acme-tiny
    __letsencrypt_acmetiny_base
    # Issue a certificate for dolibarr.example.org
    __letsencrypt_acmetiny "dolibarr.example.org"
    # Configure Nginx to serve Dolibarr with PHP support
    __evilham_nginx_site dolibarr.example.org \
        --default-server \
        --type "raw" \
        --root-dir "/usr/local/www/dolibarr/htdocs" \
        --custom-config "$(cat <<- EOF
        index index.html index.htm index.php;
        location ~ \.php$ {
            include /usr/local/etc/nginx/fastcgi_params;
            fastcgi_pass unix:/var/run/php7.4.sock;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
        }
    EOF
    )"
    # Actually setup Dolibarr
    __evilham_dolibarr \
        --unique-id "f82802ae82ab3f833c4d530b337ebd96" \
        --php-packages "ldap openssl" \
        --database-host "db.example.org" \
        --database-user "dolibarr" \
        --database-pass "$(cat "secret/hosts/db.example.org/dolibarr_database.pass")" \
        --force-sender-hack "noreply@example.org" \
        --force-bcc-hack "contact@example.org" \
        --custom-options "-" <<-EOF
    // LDAP
    \$dolibarr_main_auth_ldap_host='ldap://ldap.example.org';
    // It looks like Dolibarr does STARTTLS but not LDAPS
    \$dolibarr_main_auth_ldap_port='389';
    
    \$dolibarr_main_auth_ldap_dn='cn=users,dc=example,dc=org';
    \$dolibarr_main_auth_ldap_login_attribute='uid';
    \$dolibarr_main_auth_ldap_admin_login='cn=dolibarr,ou=Services,dc=example,dc=org';
    \$dolibarr_main_auth_ldap_admin_pass='$(cat "secret/hosts/ldap.example.org/dolibarr_ldap.pass")';
    
    \$dolibarr_main_restrict_ip='2a0a:beef:c0ff::ee/64';
    
    \$dolibarr_main_authentication='ldap,dolibarr';
    EOF
    # Go back to being parallel
    unset CDIST_ORDER_DEPENDENCY




SEE ALSO
--------
- https://www.dolibarr.org/
- `__nginx_server(7)`
- `__nginx_site(7)`
- `__letsencrypt_acmetiny(7)`
- `__letsencrypt_acmetiny_base(7)`


AUTHORS
-------
Evilham <contact@evilham.com>


COPYING
-------
Copyright \(C) 2021 Evilham.