This is a short howto to help you to set up a Sputnik wiki. More infos can be found at http://spu.tnik.org . Contents ======== 1. Setting up a Sputnik cgi 2. Configuration Parameters 3. Nice URLs 4. Access control 5. Git backend 6. Sqlite3 backend 7. Using Apache2 as a proxy 8. Using a system wide instance of Xavante Setting up a Sputnik instance ============================= To create an instance of a Sputnik wiki please use the `sputnik make-cgi` command. Note that some parameters can be passed to this command, like the directory in which Sputnik will store the date of the wiki, or the `--without-luarocks`. This will produce two files in your current working directory: - `sputnik.ws` can be used to start Sputnik in Xavante, a web server that is included with Sputnik; - `sputnik.cgi` can be used with any CGI server and can be easily adapted for use with FastCGI. To start Sputnik with Xavante, use: sputnik start-xavante This will start Xavante on port 8080. Please see "sputnik help" for more options. To use Sputnik via CGI, use sputnik.cgi as your CGI script. You may need to correct your the first line to point to the right version of Lua. You will also need to set the correct permissions. If you want to use the FastCGI mechanism instead of the classic CGI one, you can edit `sputnik.cgi` and replace the last two lines with: require("wsapi.fastcgi") wsapi.fastcgi.run(my_app) You will also need to install wsapi-fcgi package. Configuration Parameters ======================== sputnik.ws and sputnik.cgi files generated with "sputnik make-cgi" define a number of configuration parameters that control Sputnik's behavior. This is the minimum set of parameters that is necessary to get Sputnik running. Once Sputnik is running, however, you can edit additional parameters by navigating to "sputnik/config" node in your browser. You will need to login as `Admin` to edit this node. To create this account, just click on the "register" link, enter "Admin" as the user name and choose what you want the admin password to be. To learn about the different parameters, use "sputnik topic" command. Please note that some of the configuration parameters are applied immediately, but others will only apply once Xavante is restarted. Nice URLs ========= So far the URLs are something like `http://yourdomain:8080/?p=somepage` or `http://yourdomain/cgi-bin/sputnik.cgi?p=somepage`. Setting the sputnik `USE_NICE_URLS=true` variable you can obtain URLs like `http://yourdomain:8080/somepage` `http://yourdomain/wiki/somepage`. When Sputnik in its own dedicated Xavante instance (using "sputnik start-xavante"), setting USE_NICE_URLS to true is all you need to do. For other setups, however, you may also need to change the BASE_URL to reflect the URLs you want to use and to configure proper rewrite rules for your web server. See documentation available through "sputnik topic urls" and the project's wiki for more information. Access control ============== After creating the `Admin` user, you may want to make the wiki read-only or only allow edits by authenticated users. To edit permissions for all nodes, login as `Admin`, navigate to the "@Root" node, click on the "Configure" button, then edit the permissions rules in the "Permissions" box under "Advanced Fields". For example, to disallow edits by non-admin users you would need to comment out the following line (the initial -- starts a comment): -- allow(all_users, edit_and_save) -- edit, save, preview You can also set permissions for individual nodes by clicking on the "Configure" button for those specific nodes. It is also possible to set permissions for a class of nodes by creating a "prototype" nodes, configuring it, and setting node as a "prototype" for all nodes that should have the same permissions. You may also inhibit the registration of new users. To achieve this you have to set the `DISABLE_REGISTRATION=true` variable in the configuration node ("sputnik/config"). If you want to allow anonymous edits, but you want an additional protection from spam, you may use the recaptcha service adding the following lines to your `sputnik.cgi` conf table: CAPTCHA_MODULE = 'recaptcha', CAPTCHA_PARAMS = { PUBLIC, PRIVATE}, Note that `PUBLIC` and `PRIVATE` here are values that you get with you recaptcha account. This mechanism is also used to protect new users creation. You can also require email verification of new accounts. You need a working SMTP server and to add the following lines to your `sputnik.cgi` conf table: SMTP_SERVER = "localhost", SMTP_SERVER_PORT = "25", SMTP_USERNAME = "username", SMTP_PASSWORD = "pa$$w0rd", The last three parameters are optional. Configuring your Sputnik to email account verification will also automatically allow users to reset their password via email. (The passwords will never be sent by email but the user will be able to get a temporary token that would allow them to reset their password.) Git backend =========== If you want to use a Git-based backend, instead of the plain file default one, put the following snippet in your configuration table. VERSIUM_STORAGE_MODULE = 'versium.git', Also remember to run `git init` in the wiki-data directory as the user that will run Sputnik (`www-data` if you use Apache or system wide Xavante) and to _end_and_start_the_path_ with a '/', otherwise it will not work (this also means the path has to be absolute). Using the Git backend gives you the following benefits: 1. You can access your wiki history without the browser by just using "git log" (e.g. "git log Home_Page.lua") 2. You can edit files by hand, then commit changes through Git, and those changes will then show up in Sputnik's history. 3. You can pull files from the server that runs Sputnik onto your laptop, edit them locally in your favorite editor, commit, push, and the changes will appear (with history!) in the Sputnik running on the server. (Or, you can sync data between two Sputniks - e.g., one running on the server and one running locally.) 4. If you are doing 3 and meanwhile someone edits the data on the server, you can actually merge them. SQLite3 backend =============== To use the sqlite3 backend you can put the following snippet in your configuration table. VERSIUM_PARAMS = { '/some/path/wiki-data.db' }, VERSIUM_STORAGE_MODULE = "versium.sqlite3", The wiki-data.db file should not exist, but make sure your web server has permissions to create it. Using Apache2 as a proxy ======================== Xavante is a nice piece of software, but you may want to use a well tested alternative like Apache at least to proxy your Xavante daemon protecting it. Assuming you are running Xavante on localhost:8080, the following Apache2 snippet plus the command `a2enmod proxy_http` should do the job: ProxyRequests Off Order deny,allow Allow from all ProxyPass / http://localhost:8080/ ProxyPassReverse / http://localhost:8080/ Using a system wide instance of Xavante ======================================= If you want to use a system wide instance of Xavante you may find the following notes useful. Nevertheless this is more complex and the recommended solution is to use `sputnik start-xavante`. You have to edit the configuration file of Xavante and create a generic WSAIU handler for the Sputnik CGI with an entry like the following one: { match = { "^/sputnik.ws$" }, with = wsapi.xavante.makeGenericHandler(PathToCgi, {isolated=false})}, Be careful to not omit the last parameter, since it avoids a caching mechanism that makes Sputnik behave wrongly. PathToCgi is the directory in which you placed the Sputnik `ws` file. Remember to require 'wsapi.xavante' at the beginning of the configuration file. To have nice URLs with system wide instance of Xavante you have to tune its configuration file further. Add the following lines to your Xavante configuration file: { match = "^[^%./]*/$", with = xavante.redirecthandler, params = {"/sputnik.ws"} }, { match = { "^/wiki$" }, with = xavante.redirecthandler, params = {"/sputnik.ws"} }, These rules make requests to `http://yourdomain/` and `http://yourdomain/wiki` to be handled by the wiki's main node. { match = { "^/wiki/(.*)$" }, with = xavante.redirecthandler, params = {"/sputnik.ws", function(req,res,cap) req.cmd_url = "/sputnik.ws?p="..cap[1] return "reparse" end } }, This rule rewrites URLs like `http://yourdomain/wiki/yourpage` to `http://yourdomain/sputnik.ws?p=yourpage` specifying a custom action to the redirection handler.