1. Advanced scripting

This website is using Pwic.wiki behind the reverse proxy nginx to deliver the content that you are reading. All the configuration and the administration are done by shell remotely with no GUI at all. For your curiosity, here is an overview of the scripts that we use for its maintenance.

1.1. Instant setup

To start the setup, you can use a wizard which purpose is to generate an automatic script. It is a great and painless executable file for instant roll-outs!

1.2. Fake instance

If you need a dummy HTTP server during the time you configure your tools and network for Pwic.wiki, you can use the following program instead of pwic.py:

from aiohttp import web

async def handle(request):
    return web.Response(text='The website is under configuration. Stay tuned!')

app = web.Application()
app.add_routes([web.get('/', handle)])
web.run_app(app, host='127.0.0.1', port=8080)

Then execute python3 script_above.py & to start this temporary server in the background until your console is closed.

1.3. Periodic optimization

If your instance executes write operations very often, the documentation of SQLite states that long-running applications might benefit from running an optimization every few hours.

python3 pwic_admin.py execute-optimize
# or: ./pa execute-optimize

Your cron task should look like this:

0 */3 * * * script_above.sh

Remind to enable the option db_async if the drive occupation reaches its maximum. The FAQ explains why.

1.4. Monthly rotation of the logs

The concept is to compress the log files at night every first day of the months:

./pa stop  # Unlock the files
./pa rotate-logs --count 12
./pa start

Your cron task should look like this:

00 00 1 * * script_above.sh

Note: you need the essential compression tool gzip to be installed on your system.

1.5. Installation of a new release

./pa stop
git pull
# Run the manual corrections for Git (if any)
# ./pa execute-sql (if instructed by 'git log')
./pa clear-cache
./pa start

1.6. Renewal of the HTTPS certificate

This scenario is explained here. Every 80-90 days, the TLS/SSL certificate must be regenerated automatically:

cd /pwic-final-path/acme
python3 acme_tiny.py --account-key ../account.key --csr ../domain.csr --acme-dir . > ./pwic_https.crt
mv -f pwic_https.crt ..

In return, you should read the following lines:

Parsing account key...
Parsing CSR...
Found domains: pwic.wiki
Getting directory...
Directory found!
Registering account...
Already registered! Account ID: https://acme-staging-v02.api.letsencrypt.org/acme/acct/00000000
Creating new order...
Order created!
Already verified: pwic.wiki, skipping...
Signing certificate...
Certificate signed!

If you have no reverse proxy server, restart Pwic.wiki:

./pa stop
./pa start

Else, tell nginx to reload the configuration:

/etc/init.d/nginx reload

2. Develop bots

A bot is a program that performs automatic modifications in the database. You can use any compatible programming language but we recommend Python.

Pwic.wiki has a callable API that is used by the main front-end. Some code samples are available in the folder static/api/. The complete list of error codes are summarized on this page.

3. Special pages

A special page is a page that cannot be rendered in Pwic.wiki without few lines of code. To show you the capabilities of the application, this website embeds 2 pages of that kind.

3.1. API return codes

The page for the API return codes is a visual representation of the HTTP errors that you can get by calling the API. The concept is to parse Pwic.wiki's Swagger file and to produce the corresponding Markdown text on the fly.

The reserved page is en/api_rc and contains the default Markdown text that explains the purpose of the page. The bottom part of the page needs to be generated.

Add this function at the end of the file pwic_extension.py:

def get_swagger_rc_md() -> str:
    # Build yourself the content of the variable 'md' from the Swagger file
    return md

Because the function produces Markdown text only, we can expand the method PwicExtension.on_markdown_pre that runs before the internal processor md2html:

def on_markdown_pre(...) -> str:
    if (project == 'en') and (page == 'api_rc'):
        markdown += get_swagger_rc_md()
    return markdown

The final output will be stored in the cache.

3.2. Wizard

The wizard is a page that produces a script to install Pwic.wiki easily. You cannot write HTML input fields in Markdown, neither write some JavaScript (it is removed by the internal sanitizer). So the concept is to enrich the HTML output that suffers from no additional processing.

The reserved page is en/wizard and contains the following basic Markdown text. The middle line is the arbitrary mark to locate where the text needs to be enhanced.

[Go back](/en/install)

[[en:wizard]]

You can add additional text here if you want.

On the server, you prepare an HTML file that must work standalone outside of Pwic.wiki. It is made of 3 technical blocks:

the web form,
an hidden code block that is neither parsed by MathJax, nor Pygments,
a script in JavaScript.

To embed the content into the page, you implement PwicExtension.on_html() like that:

def on_html(...) -> str:
    if (project == 'en') and (page == 'wizard'):
        with open('./templates/html/z_en_wizard.html', 'r') as f:
            html = html.replace('<p>[[en:wizard]]</p>', f.read())
    return html

The output will be stored in the cache.

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