Related pages: 🇫🇷 Support
1. General approach
The issues and enhancement requests must be submitted via the public issue tracker on Github. Beware to not expose any sensitive data.
Because Pwic.wiki's code base is extendable, if your requirement can be handled with some custom code, it will not reintegrate the code base for everyone. We can discuss of new features if they are not specific to your own requirements only.
To date, no consulting services are provided to help you to write custom extensions and bots. But you can be helped to determine if your requirement is feasible or not. If not, new extensions in the code base can be added for everyone.
2. Video tutorials
The videos are available on the official YouTube channel:
- #1 Technical setup
- #2 Create your first page
- #3 Write your first article
- #4 Define the options
3. Technical FAQ
3.1. How can I check if Pwic.wiki has the feature that I need?
The features are listed of this website. They can also be compared in detail on the website WikiMatrix.org.
3.2. Is Pwic.wiki stable and safe to use?
Pwic.wiki offers a stable release 1.0 since July 2022, but also an early access to the latest changes through the git repository. You pick the version of your choice, but for the current website, it is always the latest development version to prove that it rocks. The internal development cycle always gives the priority to the resolution of the known bugs over the addition of new functionalities.
3.3. What is the structure of the files?
pwic.pyis the main code that your are not expected to change.pwic_lib.pyembed the shared functions and few changeable options.pwic_admin.pyis a script to administrate the application through a terminal.pwic_extension.pyis the code that you can modify to change the behavior of the application.pwic_importer.py,pwic_exporter.pyandpwic_md.pyare Markdown converters that you are not supposed to edit.
3.4. How do you ensure the quality of the code?
flake8 and mypy are mostly used to verify the basic syntax and the typing of the variables across the function calls. These checks are static but help a lot to anticipate the errors. Dynamically, the code is tested in practice because it is used for the current official website. More recently, the validation has been extended discretionarily to CodeFactor.io that collects other tools like pylint, stylelint or bandit.
3.5. What are the possibilities to customize Pwic.wiki?
You can:
- Structure your data by project,
- Set flexible options,
- Set static options in the code,
- Write code in many extension points,
- Create bots that use the API,
- All the error codes are summarized here
- Modify directly the release (not recommended),
- Add translations.
3.6. Does the current website use custom code?
Yes and in application of Pwic.wiki's design. This website uses the same version that you can download.
The implemented changes prevent a bit the abuse with the online demo. So if you can't connect, you will be able to do it with your own instance.
3.7. Why is nginx serving pages on this website?
The reverse proxy server nginx is used to serve the static files as recommended in the documentation of aiohttp. It is not mandatory to use it but it is better to lower the CPU workload and increase the response time. In our case, it is also a mandatory tool to share the main port 80 with other private applications and web sites (like musique.pwic.wiki).
3.8. Can Pwic.wiki run on Raspberry Pi 5?
The software in version 1.2 is validated to run on Raspberry OS inherited from Debian Bookworm 12.2. Currently, you are connected on this machine that supports both IPv4 and IPv6:
3.9. Can Pwic.wiki run in Docker?
Yes, the procedure is explained here for informational purposes.
3.10. Can Pwic.wiki use HTTPS with Let's Encrypt?
Yes, the procedure is explained here. You need to buy a domain name at least.
3.11. What is Pwic.wiki's raw memory footprint?
This is a raw sample screenshot for a virtual test server running 2 GB of memory just after Pwic.wiki started:
| User | PID | %CPU | %Mem | VSZ | RSS | TTY | Stat | Start | Time | Command |
|---|---|---|---|---|---|---|---|---|---|---|
| pwic | 979 | 0.4 | 1.9 | 62500 | 39288 | pts/0 | S | 23:23 | 0:00 | python3 pwic.py |
After 1 month running in a real machine with 8 GB of memory:
| User | PID | %CPU | %Mem | VSZ | RSS | TTY | Stat | Start | Time | Command |
|---|---|---|---|---|---|---|---|---|---|---|
| pwic | 859 | 0.0 | 1.0 | 247392 | 85792 | ? | S1 | Nov04 | 0:23 | python3 pwic.py |
3.12. How can I use several CPUs?
In case you have intensive requirements, you need to follow this procedure. The idea is to run several instances of Pwic.wiki that listen of different internal ports behind a reverse proxy server. If you don't use the option keep_sessions, each node will have its own authentication and you could not switch to another node.
The instance Pwic.wiki on this server utilizes only 1 CPU.
3.13. How can I fix the limited speed of the database?
By design of the API, each call is a database transaction, that is a collection of cancellable modifications until they are saved on the disk surface. Making sure that the data are physically saved takes time. When you call the API in mass several times, the time spent to wait becomes very high and this explains why you can't make more than say 20 inserts per second. This behavior is documented, normal and safe.
The way to do a single commit consists in updating the database directly with a custom script, which is not recommended because it bypasses all the protections. You should use the API but you don't want to be slowed down. So, to unleash the database and release the bottleneck of the hard drive, you should instruct the database to act asynchronously through the option db_async. Thousands of inserts can then be done per second but your modifications can be lost if your computer is disconnected from its power supply. This option must be used when you have a huge activity.
3.14. What are Pwic.wiki's metrics?
On 28th April 2024, with the help of AlDanial/cloc v1.92 and after disambiguation:
| Language | Files | Blank | Comment | Code |
|---|---|---|---|---|
| Python | 9 | 1340 | 4303 | 8682 |
| HTML | 25 | 309 | 6 | 2704 |
| PO File | 2 | 648 | 56 | 1324 |
| JavaScript | 14 | 126 | 63 | 1275 |
| Sass | 2 | 224 | 63 | 803 |
| XML | 2 | 0 | 4 | 202 |
| Markdown | 1 | 38 | 0 | 132 |
| CSS | 1 | 1 | 0 | 8 |
| Bourne Shell | 1 | 1 | 1 | 8 |
| DOS Batch | 1 | 1 | 1 | 8 |
| Sum : | 58 | 2688 | 4497 | 15146 |
3.15. Which Markdown standard is supported?
The current implementation done by the dependency python-markdown2 is based on CommonMark and is compatible with Github in broad outline.
3.16. Which OpenDocument standard is supported?
The integration with OpenDocument Text (ODT) follows the specification "Open Document Format for Office Applications (OpenDocument) Version 1.2" released in 2011.
3.17. Where is the list of the supported lexers?
If you installed the optional dependency pygments, you can highlight your source codes. The following sample uses abap fortuitously:
REPORT zlexers.
START-OF-SELECTION.
WRITE 'Refer to the short names given at the link: https://pygments.org/docs/lexers/'.
WRITE 'Download this page to MD file to view the expected syntax around ```'.
3.18. Will you develop an efficient and fast bug tracker based on Pwic.wiki?
Due the time and costs, this is not planned yet but fundamentally desired.
3.19. Can I contact your team in private?
If you discover a critical problem that you don't want to disclose, please get in touch by email at "support pwic.wiki" (guess the missing character). Else please use the public issue tracker whose link is given above.
Attached documents
Revision #1 was last modified by gitbra
on 2024-11-30 at 00:00:00 — 6ff021e707a1a7d7