create new tag
, view all tags

Portable TWiki

The content of this page has been split up into two topics with names which are more appropriate:

  • TWikiPersonal - for a description, installation and usage instructions
  • TWikiPersonalDev - for developers interested in how it is done or extending its features.

This page keeps the discussion during the initial stages of the project. The complete text before splitting is available at rev. 2 of this topic.


...moved to TWikiPersonalDev


...moved to TWikiPersonal

Installation instructions

...moved and updated to TWikiPersonal

Security considerations

...moved to TWikiPersonalDev

Known limitations and bugs

...moved and updated to TWikiPersonal

Questions and Answers

...moved and updated to TWikiPersonal

Build instructions

...moved and updated to TWikiPersonalDev

-- Contributors: Harald Jörg - 2015-04-19


Very cool stuff, thank you Harald!

-- Peter Thoeny - 2015-04-20

I am thinking about distribution and naming convention.

  • The "TWiki For Windows Personal" is outdated and runs on Windows only.
  • The "TWiki for all Platforms" on SourceForge.net contains the default distribution (TWiki-x.x.x.tgz, TWiki-x.x.x.zip, TWiki-VM-x.x.x.ova).
  • The "PortableTWiki" runs on multiple platforms, multiple executables are expected.

Based on this, how about:

  • Renaming "PortableTWiki" to "TWiki Personal" - it's for personal use, and it runs on multiple platforms.
  • Create a new "TWiki Personal" folder on SourceForge.net, and a "TWiki-P-6.0.1" folder below that.
  • Upload the twiki.exe and other executables into that folder.

-- Peter Thoeny - 2015-04-20

I have no problem with renaming. I just wanted to get out of the way of the endless threads in the other topics and find a quiet space where to document what it does, how to use it, and how to build it. After all, it is different from the other approaches. However, it isn't exactly multi-platform: If a Perl interpreter is bundled with it, there's still one executable per OS. Which brings me to an interesting topic: The granularity of "bundling". The TWiki release as a tgz file is at one end of the spectrum, and a TWiki VM is on the other end, and I call them "not enough integration" and "too much integration", respectively. Here, we're talking about the space in between.

  • On Windows (where I wanted to have it first, for my own purposes) it is not so common to find Perl installed. If you do have Perl installed, then you are most likely a Perl developer, and you belong to a tiny fraction of what I'd call the TWiki market. On the other hand, why would you install a VMware player plus a guest system competing with your disk space and RAM if all you want to use is one application? Tablets/convertibles often come with 32GB operating system, 2GB of RAM, and a 32GB SSD, so "hardware limitation" came back unexpectedly.
  • On Linux, there's always some version of Perl. And there are software package repositories. I guess that practically every Linux user knows how to install additional software with his package manager. Yet configuring an Apache HTTPD and its interface to Perl applications is still a challenge.
So, for TWiki Personal on Windows, I claim that providing the executable as part of the package is mandatory. On Linux it isn't mandatory, but it isn't totally worthless either. There are pros and cons.
  • Contra packaging:
    1. Developer: It is an extra step for the developers to build the package. To build an executable for an architecture, you must have a system with that architecture available.
    2. Developer: Testing on different target systems can be a nightmare, or at least: expensive. I took my family members hostage (their computers, to be precise) to test the behaviour of the Windows executable on different systems with no perl installed. Bribed them with good chocolate.
    3. Developer: As a provider of a bundled solution, you have the responsibility to monitor the lifecycle in general, and security patches in particular, for all components of the solution.
    4. User: As a user of a bundled solution, you need to install patches for every component, or at least to evaluate whether to install or whether to take the risk (think ITIL change management).
    5. User: Having several packaged Perl solutions on one system fills the space with duplicates. I have seen (and I loathe) the practice of Java programs to bring their own runtime each.
  • Pro packaging:
    1. Developer: Precise control over the software features which are in the bundle. We have this issue with CGI, where most versions will work, but recent ones won't. TWiki Personal has the issue with Plack, where we need 1.003 (or newer). Asking people to install software with CPAN is much more than asking them to use the package manager, and it leaves the problem of software lifecycle management to the end user. If we bundle the interpreter, we can extend this advantage to perl itself. For concrete examples look at the history of Perl's Unicode support in different versions, or at the very entertaining and not-yet-finished story of smart matching, or at the bug reports we had for Perl 5.18.
    2. Developer: Less effort to test with different software versions (not that we spend too much time on that hehe! ).
    3. Developer: Easier to reproduce users' problems without endless interrogations about their environment.
    4. User: Easier to deploy, in particular on Windows.

Honestly, I have no clear idea how far the bundling should go for Linux systems. As long as we need to support old Perl versions, we can't make use of new syntax features anyway. My best guess is that is still worth to consider bundling the layer between Perl and TWiki, i.e. the non-core modules: Old systems can thus use new features, and users of new systems are protected against e.g. incompatible changes in CGI provided by their platform. On Linux, we have production systems which need a high-performance web server, but I am sceptical about the "personal Linux" user.

My current preferences would be like this:

  • On Windows, go all the way up to an executable, so that people "without Perl" can use TWiki, and make this downloadable. This could be either a comprehensive TWiki installation archive containing the executable plus data, pub and the other directories, or a "executables only" archive to be used on top of a "normal" TWiki archive. Maybe there's also a need for an intermediate integration for productive use as a collaboration server in a windows environment, allowing a high-performance web server.
  • On Linux, package TWiki and its prerequisite modules, but leave out the interpreter. That way, users can easily choose their web server software (available from their friendly package manager).

-- Harald Jörg - 2015-04-27

I agree on Linux to make it more flexible as you describe. More technical knowledge is assumed for Linux users, so this should be fine.

On Windows possibly package as an executable + regular TWiki archive? That way you get the whole package in one download, and you are ready to go after unpack. As long as all the files are below one TWiki root, it is easy to copy/move a working copy of TWiki with drag and drop (such as to a memory stick). The advantage of having the TWiki data, pub and libs separate from the executable is that it is easy to patch a bug or get a new core feature by copying over files.

-- Peter Thoeny - 2015-04-27

Good points... I am still experimenting with different setups and packaging methods. A regular TWiki archive is required anyway: The packaging will only cover paths which are resolved by Perl via @INC, which can only cover the lib directory.

I am not so sure about having everything below one TWiki root. I'm always in favour of separating programs from data, which isn't so easy if there's one single root, though I have no good solution for this. "Data" in TWiki would be the data and pub directories, but with the exception of data/TWiki and pub/TWiki which I want upgraded whenever I install a new version.

So, there's some flexibility for packaging into the executable left. Here's my current preferences:

  1. The Perl executable and the core libraries:
    • On Windows, to be packaged into the executable.
    • On Linux, don't package. Use your system's Perl to start the TWiki PAR archive. This may change only if we want to use contemporary Perl syntax.
  2. Perl non-core libraries: Can be done either way, but I have a clear preference.
    • On Windows, pack into the executable. This also covers DLLs for XS modules (e.g. CPAN:HTML::Entities). If we assume Windows users don't have Perl, then learning how to CPAN is to much of a burden.
    • On Linux, pack into the PAR file. That way, we have control over the versions, and users don't have to figure out what's available in the distribution and what needs to be installed from CPAN, and there's no interference with other applications running on the same server.
  3. TWiki libraries: Can be done either way, my preference isn't so clear.
    • IDEA! Packaging lib/TWiki into the executable does not prevent bug fixes and feature extensions: There's always a lib directory outside the executable. This is a necessity for LocalSite.cfg and for user-installed extensions. So, for a bug fix, you'd just drop the fixed module(s) into the appropriate subdirectories of lib. Hotfixes would be archives containing all relevant modules, as are TWiki extensions. If the packaging process misses a non-core Perl module (maybe one required for a Plugin), it can be also be added in this way!
    • On Windows, right now I've packaged them into the executable.
      • To be honest, I'd prefer it this way because I can easily see what I've installed on top of the default TWiki installation.
    • On Linux, I suggest to add them to the PAR archive for the very same reasons.
  4. templates, locale, tools: Can't be packaged, though they are part of the distribution and "Personal" users are unlikely to fiddle with them.
  5. bin: Unused by the PSGI engine. There be dragons: Some things will break, and it will take more time to test what breaks because of that. Right now, PSGI only handles requests which are processed through TWiki::UI::handleRequest.
  6. working: Can't be packaged. Needs to be "user writable", so slightly different from those above.
  7. data and pub: Can't be packaged, and shouldn't. These are "my" personal data, and unlike all other stuff it is my responsibility to care for backups of these.

There's two defects I'm currently working on:

  • "Moving TWiki around" doesn't work because the bootstrapping procedure creates absolute paths in LocalSite.cfg. Yes, this can be fixed with configure, but if you fix it you are most probable to miss the notorious $TWiki::cfg{TemplatePath}.
  • BackupRestorePlugin doesn't work with PSGI because it has a non-standard invocation (not based on TWiki::UI). I consider this a blocking point.

-- Harald Jörg - 2015-05-01

I've updated the features and build instructions according to the current status, and here are some comments on previous comments:

  • Packing: From now on, the TWiki libraries are packed into the executable and not available from the zip as separate files. I found that the packager does dependency checking and picks whatever he finds into the executable. So, one could opt to ship with a complete lib directory, but this would just duplicate all TWiki modules with exception of those which CPAN:Module::ScanDeps doesn't detect.
  • Moving TWiki around works. Per default, all paths are relative to the installation directory.
  • BackupRestorePlugin has general problems on Windows, totally unrelated to the packing process. So I do no longer consider this a blocking point.

Further issues and topics include:

  • User management: Even on a single-user machine login apparently can't be switched off completely. I tried to run without login manager, but then failed to create a new web. That's why I kept the initial configuration step (admin password). Maybe we should just teach people to change AdminUserLogin and AdminUserWikiName to their own names, or tweak the initial configuration to that end. One could, of course, design a special login manager and user manager for Personal TWiki, but I doubt that I spend time on that soon.
  • TWiki logo as application icon: Most attempts to change the default pp logo to the TWiki result in a corrupted executable, I've given up on that. On my own systems I just create a link (Windows .lnk) on my desktop / task bar and change the icon for this link.
  • Upgrade management: This is basically the same as for every TWiki, only that on Personal AdminSkillsAssumptions are ... just wrong.
  • Creating the "right" distribution: For personal use, the set of different / helpful plugins may differ from a server installation, in both directions. Or maybe we bhave to exclude some plugins because they don't work properly (again, BackupRestorePlugin comes to my mind).

-- Harald Jörg - 2015-05-21

Good progress Harald!

As discussed, please create a new "TWiki-Personal" directory (or the like) on the TWiki repository on SourceForge. As discussed in yesterday's KampalaReleaseMeeting2015x05x21 I already moved the legacy stuff to a "Archive" directory.

-- Peter Thoeny - 2015-05-22

Done! The directory is "staged for 3 days", so should be accessible for the next release meeting.

-- Harald Jörg - 2015-06-01

TopicClassification TWikiDeployment
TopicSummary Run TWiki without installing a web server and without installing Perl


Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatpatch t602alpha.patch r2 r1 manage 15.3 K 2015-04-20 - 05:43 HaraldJoerg Missed one patch in r1
Edit | Attach | Watch | Print version | History: r11 < r10 < r9 < r8 < r7 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r11 - 2015-06-06 - HaraldJoerg
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.