README.md 6.48 KB
Newer Older
André Kerkhoff's avatar
André Kerkhoff committed
1
# Foswiki Cookbook
2

André Kerkhoff's avatar
André Kerkhoff committed
3
This cookbook installs and configures [Foswiki](https://www.foswiki.org/).
4

André Kerkhoff's avatar
André Kerkhoff committed
5
## Requirements
6

André Kerkhoff's avatar
André Kerkhoff committed
7
Currently only Debian is supported. Apache is supported but does not have to be used.
8

André Kerkhoff's avatar
André Kerkhoff committed
9
## Installation
10

André Kerkhoff's avatar
André Kerkhoff committed
11
With the default recipe a single wiki instance will be installed. Fot this the attributes `['foswiki']['download_url']`, `['foswiki']['install_dir']` and `['foswiki']['version']` can be used.
12

André Kerkhoff's avatar
André Kerkhoff committed
13
For custom wiki installations use the `foswiki_install` resource.
14

André Kerkhoff's avatar
André Kerkhoff committed
15
16
17
18
19
20
21
22
23
24
25
26
```ruby
foswiki_install name do
  checksum
  force       # default: false
  install_dir # if not name
  url
  version     # required
end
```

## Configuration

27
The default wiki installation can be configured with attributes under `['foswiki']['config']`. For example `['foswiki']['config']['DataDir']` or `['foswiki']['config']['ScriptUrlPath']`. Values for xDir attributes can contain the substring "{install}" which will be replaced with `['foswiki']['install_dir']`. Also there is a `foswiki_configure` resource. Values can be retrieved from Chef Vault. Just use the the format `{vault:#{vault}:#{item}:#{value}}` in values. Hash values have to be encoded as a string, for example `'{\'a\' => \'b\'}'`.
André Kerkhoff's avatar
André Kerkhoff committed
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

```ruby
foswiki_configure "{Path}{To}{Parameter}" do
  parameter # if not name
  value     # string or integer
  tools_dir # default: from default installation
end

# or

foswiki_configure name do
  config    # hash of parameters and values
  tools_dir # default: from default installation
end
```

## Webs

You can add a web with the `foswiki_web` resource:

```ruby
foswiki_web name do
  web_name     # if not name
  base         # default: _defaul)
  color        # default: #efefef
  list_sitemap # list web on sitemap, default: true
  search_all   # use web in global search, default: true
  summary      # string
  user         # default: root
  group        # default: root
  data_dir     # default from default installation
  script_dir   # default: from default installation
end
```

63
64
## Topics

65
The default recipe can create topics and thereby remove their existing history.
66
67
68

### System.SitePreferences

69
You can configure site preferences with attributes under `['foswiki']['site_preferences']`. To disable management of the topic set `['foswiki']['site_preferences']['disable']` to `true`.
70
71
72
73
74

For custom installations you declare a Chef template using `SitePreferences.txt.erb` as source.

### WEB.WebPreferences

75
Web preferences can be configured under `['foswiki']['web_preferences'][web]`. The `System` web is predefined. To disable management of the topics set `['foswiki']['web_preferences']['disable']` for all or `['foswiki']['web_preferences'][web]['disable']` for a specific web.
76
77
78
79
80
81
82

For custom installations you decare Chef templates using `WebPreferences.txt.erb` as source.

### Other topics

You can declare raw topics under `['foswiki']['topics'][topic] = 'content'`. Topic names can use slashes or dots as seperators between webs and topics.

83
For custom installations just use Chef's file resource. Be sure to change the modification date of the file if the correct history matters to you.
84

André Kerkhoff's avatar
André Kerkhoff committed
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
## Plugins

Every plugin in the list `['foswiki']['plugins']` will be added to the default wiki installation.

For custom installations you can use the `foswiki_plugin` resource:

```ruby
foswiki_plugin name do
  plugin_name     # if not name
  enable          # default: true
  force           # default: false
  foswiki_version # used to skip obsolete plugins
  user            # used to execute commands, default: roo)
  group           # used to execute commands, default: root
  data_dir        # default: from default installation
  install_dir     # default: from default installation
  tools_dir       # default: from default installation
end
```

## Extensions Repository

To use Foswiki plugins from sites other then foswiki.org, you can use the attribute `['foswiki']['config']['ExtensionsRepositories']` or the `foswiki_extensions_repository` resource.

```ruby
foswiki_extensions_repository name do
  repo_name # if not name
  web_url   # URL to the repositories web, required
  pub_url   # URL to the repositories web public area, required
  action    # :save (default) or :delete
end
```

## Extensions Web

A self hosted extensions web can be created by setting `['foswiki']['extensions_web']` to a name or by using the `foswiki_extensions_web` resource.

```ruby
foswiki_extensions_web name do
  web_name     # if not name
125
  color        # string, default: #efefef
André Kerkhoff's avatar
André Kerkhoff committed
126
127
128
129
130
131
132
133
134
135
136
137
138
  list_sitemap # list web on sitemap, default: false
  search_all   # use web in global search, default: false
  user         # default: root
  group        # default: root
  data_dir     # default: from default installation
  install_dir  # default: from default installation
  pub_url      # default: from default installation
  script_dir   # default: from default installation
  tools_dir    # default: from default installation
  view_url     # default: from default installation
end
```

139
140
141
142
143
144
145
146
147
148
149
## Unofficial patches

This cookbook provides some unofficial patches for Foswiki which can be controlled with attributes under `['foswiki']['patches']` or a `foswiki_patches` resource.

```ruby
foswiki_patches name do
  holidaylistplugin # Make HolidaylistPlugin compatible with newer Perl versions and add option "priopubholidays"
  noproxy           # Add the configuration item {PROXY}{NoProxy} (https://foswiki.org/Development/AddNoProxyFeature)
  owner             # owner of patched files
  group             # used group for patched files
end
150
151
152
```

Moreover if `['foswiki']['config']['Cache']['Enabled']` is set to `true`, a script called `tidy_page_cache.sh` is installed under the tools directory. This can be used to remove orphaned or unnecessary entries. With `['foswiki']['cron']['tidy_page_cache_time']` the script can be run regularly.
153

André Kerkhoff's avatar
André Kerkhoff committed
154
155
156
## robots.txt

Foswiki's robots.txt can be configured with `['foswiki']['robots']['crawl_delay']` (Integer) and `['foswiki']['robots']['disallow']` (List). For custom installations the template `templates/robots.txt.erb` can be used.
157
158
159
160

## Apache configuration

Optionally you can use the `foswiki::apache` recipe. See `attributes/apache.rb` for attributes which are used in it. It only includes the apache2 cookbook and configures a web_app resource. The web_app template `templates/web_app.conf.erb` can be used in custom wiki installations, as well.
161
162

The recipe automatically configures FCGI and XSendFile if the plugins [FastCGIEngineContrib](https://foswiki.org/Extensions/FastCGIEngineContrib) or [XSendFilePlugin](https://foswiki.org/Extensions/XSendFileContrib) are listed in `['foswiki']['plugins']`.