1. Installation

The file README.md gives a quick procedure, but let's go into details below.

Don't be afraid by the length of the page, it is very easy!

1.1. Wizard

If you want to install Pwic.wiki by shell and with guidance, you can follow this wizard. Answer few questions, run the downloaded script on your host, and jump to the next chapter.

Else, continue to read.

1.2. Code interpreter and tools

Install Python ≥3.7 as root:
- Linux: apt-get install python3 python3-pip --no-install-recommends is valid on Debian
- Windows: go to Python.org and use the command python below (instead of python3)
Upgrade the package manager: python3 -m pip install --upgrade pip
Install gzip if you need to rotate the HTTP logs:
- Linux : apt-get install gzip under Debian
- Windows : this Linux tool is cross-compiled here

1.3. Files

Using Git is recommended because it helps to merge your custom code. Then clone the repository: git clone https://github.com/gitbra/pwic.git
- To upgrade the source code, run git pull, merge the code and adapt the database (if required)
Else simply uncompress the latest modifications in a folder of your choice
- To upgrade the code, download the new files, adjust your custom code and the database (if required)
Install the dependencies: python3 -m pip install --upgrade -r requirements.txt
- aiohttp is the web server
- aiohttp-cors helps to query the API from another website with JavaScript
- aiohttp-session handles the connection to the website
- imagesize reads the properties of the uploaded pictures so that they can be handled well during the export of a page to HTML and OpenDocument
- jinja2 is rendering the website
- parsimonious is used to tokenize the search queries
- PrettyTable is used to improve the output of the commands in the management console
- pygments is optional and helps to colorize the source codes in your documentation
- cryptography is used by aiohttp to encode the cookies
- setuptools is optional but should be installed if you have an error message with parsimonious
Do some changes in the file pwic_lib.py to improve the security:
- The default password in PwicConst.DEFAULTS['password'] should be unique. All the new accounts are created as readers by default
- Optionally write random characters in the secret salt PwicConst.SALT. But if you change the value in the future, then all the passwords will be unrecognized and you will have the reset them by command lines

1.4. Database

Only once, initialize the database: python3 pwic_admin.py init-db
- A sub-folder db/ is created to store all your data
- The structure of the database depends on the version
Create a new project demo for the user admin for example: python3 pwic_admin.py create-project demo "Demo project" admin
Start the server locally: python3 pwic.py
Experience Pwic.wiki at http://127.0.0.1:8080 by default
Warning: change your password online before you can change the authorizations and edit the pages

1.5. Configuration

You can use many global and project-dependent variables described in the help file. By design, the most sensitive or global ones cannot be changed online.

All the options can be set by command line, which makes Pwic.wiki very convenient to deploy and maintain by shell: python3 pwic_admin.py set-env --help

Once you secured your instance, you can use the public bind address 0.0.0.0 or :: and change the port in the command line: python3 pwic.py --host 0.0.0.0 --port 8080. Under Linux, the ports below 1024 need an access as root, which is not recommended by principle for Pwic.wiki. The optional but recommended usage of a reverse proxy server or NAT rules solves this question.

2. Translations

Pwic.wiki is shipped with few default languages (EN, FR, DE). You can help to localize the application into your own language. The procedure is quite simple.

3. HTTPS

The activation of HTTPS is done in a second step after your instance is running well with the classical HTTP. Because getting a TLS/SSL certificate is complicated, a dedicated page explains the procedure.

4. Federated authentication

You can authenticate on a remote server and Pwic.wiki allows you to connect afterwards. A dedicated page explains the procedure once you finished the previous steps.

5. Two-factor authentication (2FA)

You can use a random secondary password to secure certain user accounts. A dedicated page explains the procedure.

6. BI reports

The procedure is explained on that page.

7. Advanced scripting (optional)

To view our scripts used to maintain Pwic.wiki from shell, just click here.

8. Advanced hosting in Docker

A dedicated page explains the procedure.

Revision #1 was last modified by gitbra
on 2023-12-11 at 00:00:00 — fe179e52d845f233