{"id":13557215,"url":"https://github.com/foswiki/distro","last_synced_at":"2025-12-17T02:47:53.774Z","repository":{"id":19793366,"uuid":"23052818","full_name":"foswiki/distro","owner":"foswiki","description":"START HERE!  This is the Foswiki project \"Distribution\".  It is a monolith repository with the core + default extensions.","archived":false,"fork":false,"pushed_at":"2025-12-11T19:45:27.000Z","size":131343,"stargazers_count":116,"open_issues_count":1,"forks_count":41,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-12-12T05:39:49.304Z","etag":null,"topics":["collaboration-system","enterprise-software","enterprise-webapp","foswiki","perl","web-application"],"latest_commit_sha":null,"homepage":"https://foswiki.org/","language":"Perl","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foswiki.png","metadata":{"files":{"readme":"README.md","changelog":"HistoryPlugin/.gitignore","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-08-17T23:26:53.000Z","updated_at":"2025-12-11T19:45:31.000Z","dependencies_parsed_at":"2023-10-03T23:58:35.061Z","dependency_job_id":"66118a9f-7a27-4e7f-b95b-91dc4bbcd054","html_url":"https://github.com/foswiki/distro","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/foswiki/distro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foswiki%2Fdistro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foswiki%2Fdistro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foswiki%2Fdistro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foswiki%2Fdistro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foswiki","download_url":"https://codeload.github.com/foswiki/distro/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foswiki%2Fdistro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27775739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-17T02:00:08.291Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collaboration-system","enterprise-software","enterprise-webapp","foswiki","perl","web-application"],"created_at":"2024-08-01T12:04:13.169Z","updated_at":"2025-12-17T02:47:53.759Z","avatar_url":"https://github.com/foswiki.png","language":"Perl","funding_links":[],"categories":["Perl","perl"],"sub_categories":[],"readme":"# Foswiki Installation based on git\n\n**These instructions are more geared for developers, and admins who want to use the \"bleeding edge\" of Foswiki.   We recommend using our packaged distributions.  See our [Download page](http://foswiki.org/Download/)**\n\nYou can run a Foswiki instance from this clone simply by pointing Apache at it.  See the  [ApacheConfigGenerator](http://foswiki.org/Support/ApacheConfigGenerator)\n\n*Note:Configure has been completely rewritten on the master branch.  Foswiki is now able to \"bootstrap\" itself without a configuration.*  After pseudo-installing the default extensions,\nPoint your browser at your default URL for the new site as configured in ApacheConfigGenerator.\n(ex.  `http://yoursite.com`, `http://yoursite.com/foswiki`, or `http://yoursite.com/foswiki/bin/view` depending upon the apache configuration)\n\nTo \"install\" extensions in a checkout area, you should use the `pseudo-install.pl` script to install them. On Unix/Linux this script generates soft-links from the core tree\nto the extensions, so you can work on your code in situ and see the impact of the changes on your live foswiki without needing to do an install step.\nWindows doesn't support soft links, so the script can also be run in `-copy` mode (the default on Windows), but in this case you will have to re-run it each time you change your extension.\nUse:\n - `pseudo-install.pl default` to install the default contribs and plugins (e.g. Extensions.TwistyContrib which is relied on by Extensions.PatternSkin)\n - `pseudo-install.pl developer` to install the additional developer extensions.  The developer option also installs all the default extensions.\nSee the header comment of the `pseudo-install.pl` script (core directory of checkout) for options and more information.\nNote that `pseudo-install.pl` only works with extensions that have a MANIFEST file, as required by the Extensions.BuildContrib.\n\nScript examples below are for `bash` shell.\n## Example of running pseudo-install\n\nThe typical situation is that you want to run a pseudo-installed Foswiki checked out from \"master\" branch.\nAnd if you develop plugins, you want to be able to activate your plugin in this installation. This is the entire sequence for checking out the master branch from git\nand doing the pseudo-install. We assume that you want to run your git based install in `/var/www/foswiki`\n\nThe following commands check out an _absolutely minimal_ Foswiki (the core + default user mapping only). This is the smallest checkout that will run. The steps are:\n 1. create the root directory called foswiki\n 1. `git clone https://github.com/foswiki/distro.git foswiki`\n 1. This will check out core and all the default and developer extensions, however they are not installed yet.\n 1. `cd core \u0026\u0026 ./pseudo-install.pl default`\n 1. change the ownership so the entire tree is owned by the user running the Apache. In this example the user name is \"apache\".\n 1. point Apache at the checkout\nChange the commands to fit your actual file locations and Apache user. Some commands may have to be run as root.\n\n```\ncd /var/www\nmkdir foswiki\n\ngit clone https://github.com/foswiki/distro.git foswiki\nCloning into 'foswiki'...\nremote: Counting objects: 134190, done.\nremote: Compressing objects: 100% (37847/37847), done.\nremote: Total 134190 (delta 87343), reused 132136 (delta 85289)\nReceiving objects: 100% (134190/134190), 66.86 MiB | 1.63 MiB/s, done.\nResolving deltas: 100% (87343/87343), done.\nChecking connectivity... done.\n\n# By default this will leave you in the \"master\" branch, where leading edge development happens\n# If you want to use the current release branch, change to the Release01x01 branch\n# Skip this step if you want to remain on the experimental master branch.\n\ncd foswiki\ngit checkout Release01x01\nBranch Release01x01 set up to track remote branch Release01x01 from origin.\nSwitched to a new branch 'Release01x01'\n\n# The extensions have all been checked out one level up from the \"core\" directory\n# the next step is to link / copy them into the installation.  This is done with pseudo-install.\n\ncd core\nperl -T pseudo-install.pl default\nInstalling extensions: PatchFoswikiContrib, AutoViewTemplatePlugin, CompareRevisionsAddOn, CommentPlugin, EditTablePlugin, EmptyPlugin, FamFamFamContrib, HistoryPlugin, InterwikiPlugin, JSCalendarContrib, JQueryPlugin, MailerContrib, TablePlugin, TwistyPlugin, PatternSkin, PreferencesPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TipsContrib, WysiwygPlugin, TinyMCEPlugin, TopicUserMappingContrib, TWikiCompatibilityPlugin, core\nProcessing AutoViewTemplatePlugin\nLinked data/System/AutoViewTemplatePlugin.txt\nmkdir /var/www/fw/core/lib/Foswiki/Plugins\n...\n#...\n#... A large amount of output is generated.\n#... Errors about dependencies on foswiki extensions can generally be ignored.\n#... The extensions are not installed in the order that would resolve all dependencies.\n#...\n\n\n# If necessary, change ownership of all files to the webserver user.\n# In this case that is 'apache:apache', though it may also be 'www-data:www-data'\n# e.g. on Debian and Ubuntu systems, or something else entirely. Check first.\nchown -R apache:apache foswiki\n\n# Now configure Apache to use the Foswiki in /var/www/foswiki/core\n```\n\n1. Use the [ApacheConfigGenerator](http://foswiki.org/Support/ApacheConfigGenerator?foswikiversion=1.1\u0026vhost=\u0026port=\u0026timeout=\u0026dir=%2Fvar%2Fwww%2Ffoswiki\u0026symlink=on\u0026pathurl=%2Ffoswiki\u0026shorterurls=enabled\u0026engine=CGI\u0026fastcgimodule=fastcgi\u0026fcgidreqlen=\u0026apver=2\u0026allowconf=\u0026reqandor=and\u0026requireconf=\u0026loginmanager=Template\u0026htpath=\u0026errordocument=UserRegistration\u0026errorcustom=\u0026phpinstalled=PHP4\u0026blockpubhtml=on#HighLight)\n1. Clipboard copy and save this to `core/../foswiki.httpd.conf`\n1. Include this `foswiki.httpd.conf` from your apache `httpd.conf`  OR\n  * On many linux distributions, you can save this file into `/etc/apache2/sites_enabled` or `/etc/apache2/vhosts.d`,  or `/etc/apache2/Include` ... Check your local distribution's instructions.\n  * If you are on a Mac, you can put this file into /etc/apache2/other/ and line \"Include /private/etc/apache2/other/*.conf\" will pick it up.\n  * Otherwise, edit your httpd.conf and add: `Include /path/to/foswiki.httpd.conf`\n  * Ensure your new .conf file has chmod a+r access\n**Note:** If the apache error log has lots of `Symbolic link not allowed or link target not accessible` type messages, then you probably need to add `+FollowSymLinks`\nto the `Options` for the `/var/www/foswiki/dev/core/pub` directory in your apache configuration.\n\nAt this point, if you point your browser to your foswiki url,  it should \"just work\",  but will display a bootstrap warning at the top of the configuration.  To fully configure foswiki, visit the `bin/configure`\nURL, resolve any warnings and errors, and save the configuration.  *Caution:  Once you save the configuration, you will be unable to use configure again unless you have registered and granted yourself \"Adimin\"\nauthority.*  You can control who can use configure by setting `Security and Authentication` -\u003e `Access Control` `{ConfigureFilter}`.   When that option is set, it replaces the check for Admin authority and can\nallow *any* user including the guest user to use configure.  So use caution!.\n\nNow and then you will want to keep your installation in sync with the latest version in the foswiki git repository. The pseudo-install script is not intelligent enough to cope with changes to MANIFESTs, so this is the idiot proof way to update. It first removes all the links (or copied files), git fetch. And finally does a new pseudo-install.\n```\ncd /var/www/foswiki/core\n./pseudo-install.pl -uninstall all\ngit pull\n./pseudo-install.pl default\nchown -R apache:apache ..\n```\n\nNormally just doing the git pull will be enough, unless someone has removed files (and even then you can usually ignore it).\n\nIf you are a developer you can also install the kit required to run unit tests, by passing the `developer` parameter to `pseudo-install.pl`\n```\ncd /var/www/foswiki/core\n./pseudo-install.pl developer\n```\n\nThis will also install [BuildContrib](http://foswiki.org/Extensions/BuildContrib) and a number of other components useful to developers.\n\n## Tips, hints, and useful commands\n### Enable ASSERTS for more extensive testing\n\nThe unit tests run with ASSERTS enabled, but the live web environment does not.  In order to enable ASSERTS, edit `bin/LocalLib.cfg` (If it's not there, create it by copying `bin/LocalLib.cfg.txt`) and un-comment the following line\n```\n$ENV{FOSWIKI_ASSERTS} = 1;\n```\n\nThis enables additional validation tests that will impact performance, but will catch some issues that might be missed during normal web usage.\n\n\n### Use the CPAN modules shipped with Foswiki\n\nFoswiki 1.2 no longer ships with CPAN modules. It is now recommended to use your system's package manager, or cpan to install dependencies. see http://foswiki.org/System/SystemRequirements.  In the event that you are unable to install the CPAN dependencies, pseudo-install the CpanContrib to get the 1.x style Foswiki specific dependencies. (CpanContrib is not yet released). In order to test these modules, CPAN lib prepending should be enabled in \u003cspan\u003ebin/LocalLib.cfg\u003c/span\u003eby uncommenting the following line:\n\n```\n$CPANBASE = '';                     # Uncommented: Default path prepended\n```\n\n.   See the comments in `bin/LocalLib.cfg.txt` for more details.\n\nIt is probably best to test using platform modules as well as the shipped modules.\n\n### Installing non-default extensions\n\nThe example commands above describe how to install a _minimalist_ Foswiki.    The pseudo-install script knows some additional tricks to use with non-default extensions. If you pseudo-install an extension that is not currently checked out,  pseudo-install will automatically clone the extension from github using  `https://github.com/foswiki/ExtensionName.git`\n\n**Note:** Although we use release managed branches  (master, Release01x00, Release01x01) in the Foswiki core distribution (\"distro\"), non-default extensions typically only have a \"master\" branch.\n\nHere's how to install a non-default extension, using AntiWikiSpamPlugin as an example:\n```\ncd foswiki/core\n ./pseudo-install.pl AntiWikiSpamPlugin\nUseless use of \\E at ./pseudo-install.pl line 1553.\nUseless use of \\E at ./pseudo-install.pl line 1553.\nInstalling extensions: AntiWikiSpamPlugin\nProcessing AntiWikiSpamPlugin\nTrying clone from git://github.com/foswiki/AntiWikiSpamPlugin.git...\nCloning into 'AntiWikiSpamPlugin'...\nremote: Counting objects: 489, done.\nremote: Total 489 (delta 0), reused 0 (delta 0)\nReceiving objects: 100% (489/489), 86.42 KiB | 0 bytes/s, done.\nResolving deltas: 100% (185/185), done.\nChecking connectivity... done.\nCloned AntiWikiSpamPlugin OK\nLinked data/Main/AntiWikiSpamBypassGroup.txt\nLinked data/System/AntiWikiSpamLocalList.txt\nLinked data/System/AntiWikiSpamRegistrationWhiteList.txt\nLinked data/System/AntiWikiSpamRegistrationBlackList.txt\nLinked data/Sandbox/AntiWikiSpamTestTopic.txt\nLinked data/System/AntiWikiSpamPlugin.txt\nLinked lib/Foswiki/Plugins/AntiWikiSpamPlugin.pm\nLinked lib/Foswiki/Plugins/AntiWikiSpamPlugin\nLinked test/unit/AntiWikiSpamPlugin\nLinked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/AntiWikiSpamPlugin/.git/hooks/commit-msg\nLinked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/AntiWikiSpamPlugin/.git/hooks/pre-commit\nLinked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/AntiWikiSpamPlugin/../.git/hooks/commit-msg\nLinked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/AntiWikiSpamPlugin/../.git/hooks/pre-commit\n AntiWikiSpamPlugin installed\nLinked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/core/.git/hooks/commit-msg\nLinked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/core/.git/hooks/pre-commit\nLinked /var/www/fw/core/tools/develop/githooks/commit-msg as /var/www/fw/core/../.git/hooks/commit-msg\nLinked /var/www/fw/core/tools/develop/githooks/pre-commit as /var/www/fw/core/../.git/hooks/pre-commit\n```\n\n### Delete all broken soft links\n\nThis is handy if you have changed a lot of MANIFESTS or have manually soft-linked any files, and want to remove any broken soft links. Assume your trunk checkout is at `/var/www/foswiki`.\nYou'll also need to do this when switching between Release01x01 and master branches.\n\n```\nfind -L /var/www/foswiki/core -type l -exec rm \\{\\} \\;\n```\n\n### Create a new extension\n\nYou can quickly and easily create a new extension using the `create_new_extension.pl` script that is installed in `core` when you pseudo-install the Extensions.BuildContrib.\n\n### Set up the unit test framework\n\nIf you are developing new code you will want to set up the development and test environment. For this you will need to pseudo-install !BuildContrib, !UnitTestContrib and !TestFixturePlugin.\n\n```\n./pseudo-install.pl developer\n```\n\nThen:\n```\ncd test/unit\nexport FOSWIKI_LIBS`/var/www/foswiki/core/lib\nperl ../bin/TestRunner.pl FoswikiSuite\n```\n\n(or equivalent on Windows)\n\nFor full details, see http://foswiki.org/Development/UnitTests#SettingUpATestEnvironment\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoswiki%2Fdistro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoswiki%2Fdistro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoswiki%2Fdistro/lists"}