Skip to Content
Last modified by Alexandru Pentilescu on 2023/06/25 18:56
From version 35.1
edited by Alexandru Pentilescu
on 2022/06/09 22:37
Change comment: There is no comment for this version
To version 15.1
edited by Alexandru Pentilescu
on 2022/06/08 21:25
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -9,10 +9,6 @@
9 9  
10 10  With all of these details in mind, let's begin!
11 11  
12 -{{box title="**Contents**"}}
13 -{{toc /}}
14 -{{/box}}
15 -
16 16  ----
17 17  
18 18  
... ... @@ -154,109 +154,10 @@
154 154  
155 155  [[image:Screenshot_20220607_015727.png]]
156 156  
157 -**While it may be tempting to immediately try to setup an administrator account from this portal, unless you're browsing this page from localhost (i.e. the XWiki server is on the exact same machine that you're running your web browser from) DO NOT register an account YET! All traffic is unencrypted to the server and may be intercepted by anyone sniffing your internet packets. We must first configure an X.509 TLS certificate with Nginx and configure Nginx to act as a reverse proxy for this wiki**
153 +**While it may be tempting to immediately try to setup an administrator account from this portal, unless you're browsing this page from localhost (i.e. the XWiki server is on the exact same machine that you're running your web browser from) DO NOT register an account YET! All traffic is unencrypted to the server and may be intercepted by anyone sniffing your internet packets. We must first configure an X509 TLS certificate with Nginx and configure Nginx to act as a reverse proxy for this wiki**
158 158  
159 159  For the time being, press the "Later" button on the dialog (not the "Never" one!) and then run a "docker-compose down" to stop the container from running. The first test run was a success! Congratulations!
160 160  
161 -= Nginx reverse proxy configuration =
162 -
163 -We assume you already have Nginx installed and properly configured on your machine. Also, we will assume you have an X.509 certificate whose Subject Alt Names includes both your domain name, as well as the subdomain for your wiki (i.e. in my case for pentilescu.com and wiki.pentilescu.com, respectively) and you've configured Nginx to utilize both of them! If this is not the case or you're unsure how to perform these configurations, please check the internal "How to setup an Nginx reverse proxy and also provide a global X.509 certificate for it" guide at the bottom of this page.
164 -
165 -In "/etc/nginx/sites-available/", please create a "xwiki.conf" file with the following contents:
166 -
167 -{{code language="nginx"}}
168 -server {
169 - server_name wiki.pentilescu.com;
170 -
171 - listen [::]:443 ssl http2; # managed by Certbot
172 - listen 443 ssl http2; # managed by Certbot
173 -
174 - include /etc/nginx/snippets/ssl.conf;
175 -
176 - location / {
177 - proxy_pass http://localhost:8081;
178 - }
179 -}
180 -{{/code}}
181 -
182 -Please replace "wiki.pentilescu.com" with the domain and subdomains that you desire for your particular website. Also, please adapt "/etc/nginx/snippets/ssl.conf" to reference the X.509 Nginx configuration file on your particular server. If you do not wish to support TLS at all, you may remove this line, as well as the "listen" directives from above.
183 -
184 -Effectively, what this configuration file will do is tell Nginx to redirect all HTTP/HTTPS connection verbs directed at wiki.pentilescu.com to localhost port 8081, optionally also injecting the TLS certificates into the connection to secure it as well. By doing this, instead of having to connect to port 8081 on your server manually, future users of your XWiki instance will have to type the subdomain in their browser's address bar instead, which is usually more human readable and more memorable for most people. Typing in "wiki.pentilescu.com" into your browser's address bar is more human friendly than typing "pentilescu.com:8081". Not only are numeric port numbers difficult to remember, but Nginx will also inject TLS into the connection to secure it if you configured the X.509 certificates properly, effectively securing your visitors' connection every time so that their login credentials are protected even against network sniffers.
185 -
186 -Once you've done this, create a symbolic link with the following command to activate your new configuration:
187 -
188 -{{code language="bash"}}
189 -sudo ln -s /etc/nginx/sites-available/xwiki.conf /etc/nginx/sites-enabled/xwiki.conf
190 -{{/code}}
191 -
192 -Finally, test your configuration before restarting Nginx with:
193 -
194 -{{code language="bash"}}
195 -sudo nginx -t
196 -{{/code}}
197 -
198 -If errors are reported, please review your configuration files and repair all the detected issues. If everything is fine then issue a "sudo systemctl restart nginx" and then you're pretty much good to go!
199 -
200 -= Retrieving files for installing the Standard flavor packages and all its extensions =
201 -
202 -While the docker container contains all the necessary system utilities to run the XWiki server internally, a lot of functionality for the Wiki will be missing as it is.
203 -The XWiki container is very lackluster even in administration features and not installing the Standard flavor will give you a very barebones and almost functionally broken experience. As such, while optional, it is very strongly encouraged to install the Standard flavor along with XWiki to activate many of its most basic features.
204 -To do so, we will have to download a very specific XIP package from XWiki's download portal. Visit [[here>>https://www.xwiki.org/xwiki/bin/view/Download/]] this aforementioned download portal and click the "Download" button for the Long Term Support option on that page. On the new page, click the "Download" button for the "XIP Package" section. This will allow you to download the XIP package in question to your local computer.
205 -Unzip the contents of this XIP package (XIP is just a specific flavor of a ZIP archive so you can just rename the file to use the ".zip" extension if your archive program doesn't recognize it) and upload the unzipped contents to the server where the docker image of XWiki is running, under the "data/xwiki-data/data/extension/repository/" subdirectory of your XWiki directory.
206 -Once this has been done, you may issue a "docker-compose up -d" again to start up the XWiki engine once again. Now that the files have been delivered to their expected disk location and are accessible to the engine, you will be good to go to install them efficiently.
207 -There are other means of installing the Standard flavor as well, as detailed [[here>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HOthermethods]]. Choose whichever alternative you wish!
208 -
209 -Once the XWiki engine has initialized its start state properly, you may visit your XWiki instance by going into the browser and accessing the wiki via your Nginx configured subdomain, rather than by port 8081 as we previously did. If you opted to also configure Nginx to inject TLS into the connection, you should now see the green lock in your web browser, next to the address bar, indicating that your connection to your server is encrypted and protected from any network sniffers. You may now proceed to both create an administrative account, as well as install the Standard flavor.
210 -
211 -
212 -= Initial XWiki setup for administrative account and installing the Standard flavor =
213 -
214 -At this point, you should see the following image in your browser again:
215 -[[image:Screenshot_20220607_015727.png]]
216 -
217 -It's finally time to setup the administration account! This account will have full privileges throghout the wiki and will be able to view and edit anything and everything. As such, please use a very strong password to protect it from password stuffing attacks!
218 -If in doubt, always use a password manager like Bitwarden to generate strong, long passwords for you! These are guarenteed to have high entropy and are resistant to dictionary attacks.
219 -
220 -Fill in all the details for your account, as detailed in the image below:
221 -[[image:Screenshot_20220607_015843.png]]
222 -
223 -Press the "Register and login" button to immediately login as the newly created user. Once this is done, we can proceed with the Standard flavor installation, as shown below:
224 -[[image:Screenshot_20220607_020931.png]]
225 -
226 -The "XWiki Standard Flavor" option should appear in the FLAVOR window by default if you downloaded the aforementioned XIP package and extracted its contents via the upload I already described in the proper directory. This flavor is ready to be installed now. Press the "Install this flavor" and let's get this show going!
227 -You should come up to the following screen:
228 -[[image:Screenshot_20220607_020959.png]]
229 -
230 -Press "Install".
231 -
232 -After some time, the following screen should appear:
233 -[[image:Screenshot_20220607_021031.png]]
234 -
235 -Press "Continue". Admittedly, this took several attempts on my end. I had to press "Continue" multiple times and a Time-out error appeared many times over, indicating that the process failed at some point.
236 -
237 -Not sure what was wrong, or what was even timing out. All the packages were supposed to already be provided by the XIP package which I already unarchived, so all the files should have been locally accessible for the server. Was it downloading something else in the process? Don't know.
238 -If you encounter a similar bug, please be persistent and keep on pressing "Continue" for another couple of times, like I did, around 3 or 4 times. If no progress is being made, press the "Later" button instead. If that button is disabled, press the "Select other flavor" at the top first and then press "Later", so that the installation of the Standard flavor is skipped. I did that and eventually it took me to the full Wiki page.
239 -Proceed through the next installation steps and eventually finish the setup wizard entirely.
240 -Once this is done, you should be directed to your XWiki's greeting page!
241 -Congratulations, you've finished your first installation!
242 -
243 -
244 -= Post-installation configurations that are a good idea=
245 -You've setup an administrative account, you installed the Standard flavor package and now the Wiki is up and running. You're pretty much done, right?
246 -Well, not quite...
247 -There are still certain configurations which are a good idea that you should do. First and foremost, you should disable account registration, if possible, to ensure that rogue visitors don't get to pollute your database with bogus names. The user registration process is available to all visitors, by default, and this means that literally anyone can register an account on your Wiki. Which may be what you want or it might not be. For me, I prefer creating user accounts manually as the administrator so I opted to turn off the registration option. I suggest you do the same.
248 -
249 -== Disable guest registration==
250 -Log into your administrative account if you're not already logged in. Press the hamburger menu button at the top right of the grettings page and open the side menu. From there, select the "Administer Wiki" option.
251 -On the new page, expand the "Users & Rights" left panel and then click on the "Rights" menu option. You should then be redirected to a "Global Administration: Rights" page. Here, you can micro-manage the rights of every single user and groups of users. Explaining user rights and the exact functions of each of these options is outside the scope of this wiki. For now, I'll only describe the disabling of the registration.
252 -There's a horizontal combo box on the new page with the "Groups" and "Users" options, on the top of the page. Click on the "Users" option.
253 -Here, you can micro-manage the rights of individual users. The "Register" checkbox is what we're after. We must deny registration rights to unregistered users.
254 -It may seem that this right is already denied by default for all users, given that the Registration checkboxes will appear empty on your end. This is a quirk of the XWiki access rights UX. Despite these looking like checkboxes, they are not, in fact, traditional checkboxes.
255 -In computer graphics design, one of the most fundamental lessons is that the element of a Checkbox is the graphical equivalent of a mathematical boolean variable (i.e. it must have only one of two states, at any point in time): a checkbox must either be checked or unchecked. The XWiki Rights panel has a different kind of checkbox, though, one that can take 1 of 3 states: empty, allowed and denied. In most cases, the default is the empty state.
256 -Empty means that no particular configuration has been made with respect to that right for that user.
257 -In our case, we wish to deny registration rights for unregistered users, so we have to set the "Registration" checkbox of the "Unregistered Users" row in that table to the "denied" state, like in the screenshot below:
258 -
259 259  = External references =
260 260  
261 261  [[Official docker guide for installing XWiki>>https://github.com/xwiki/xwiki-docker/blob/master/README.md]]
262 -How to setup an Nginx reverse proxy and also provide a global X.509 certificate for it -- NOT YET WRITTEN!--
Screenshot_20220607_015843.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.AlexandruPentilescu
Size
... ... @@ -1,1 +1,0 @@
1 -104.4 KB
Content
Screenshot_20220607_020931.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.AlexandruPentilescu
Size
... ... @@ -1,1 +1,0 @@
1 -97.0 KB
Content
Screenshot_20220607_020959.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.AlexandruPentilescu
Size
... ... @@ -1,1 +1,0 @@
1 -127.7 KB
Content
Screenshot_20220607_021031.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.AlexandruPentilescu
Size
... ... @@ -1,1 +1,0 @@
1 -182.0 KB
Content