------------------------------------ How to use the local Illarion server ------------------------------------ 0. Preface ---------- This server is a tool for Illarion script and map development. It allows you to test your scripts and maps locally before uploading them to the Illarion server. It can also be used for website development and even server development with a few adjustments. Also it can be helpful for client development. 1. Preparation ---------- To use the local server you need the VirtualBox application. Download and install it. You can get VirtualBox here: https://www.virtualbox.org/ You will also need a programm that understands the zip format: http://www.7-zip.org Finally get the Illarion server VM: https://illarion.org/~estralis/illarion_local_server.zip Download illarion_local_server.zip Extracting the archive will yield a folder "illarion" with four files: Illarion.vbox Illarion.vdi illarion_local_rsa illarion_local.ppk 2. Setup -------- You need to perform a few steps before you can launch the server; otherwise it will blow up in your face. If you moan to any developer without following these EXACT steps, the developer won't be pleased. First thing is that you NEED both the script and the maps repository. Without BOTH, you can't use the server. For website development you will also need the website repository. Script repository for developers: ssh://git@illarion.org:1010/scripts Map repository for developers: ssh://git@illarion.org:1010/maps Website repository for developers: ssh://git@illarion.org:1010/website If you are not an Illarion developer, you should use our GitHub mirrors: Script repository: https://github.com/Illarion-eV/Illarion-Content Map repository: https://github.com/Illarion-eV/Illarion-Map Website repository: https://github.com/Illarion-eV/Illarion-Website Now once this is done, double click the VirtualBox file to load the VirtualBox installation GUI (which should have been downloaded in Step 1). Click the file called "Illarion.vbox" which has the type description "VirtualBox Machine Definition". It has a blue cube icon. NOTE: do not click the VDI (Virtual Disk Image) file with the same name (it has a red cube icon). After that you should see the Illarion Server in your VirtualBox installation. DO NOT START IT. Rather right click it and click "Settings...". Select the "System" category on the left hand side. The virtual machine needs at least 2048 MB RAM, the default is higher. Use any amount of RAM you want to, but not less than 2048 MB. If you want to compile the server inside the VM, you should also allow the usage of as many cores/processors as you have or can afford to spare. Otherwise leave that setting at 1. On the left side the bottom entry should be "Shared folders". Access this one and add at least the first two folders mentioned below. Folder 1: Path: Select the directory where your working copy of the scripts is located Name: scripts [x] Read-only [x] Auto-mount Folder 2: Path: Select the directory where your working copy of the maps is located Name: maps [x] Read-only [x] Auto-mount (optional, for website development) Folder 3: Path: Select the directory where your working copy of the website is located Name: website [x] Read-only [x] Auto-mount Once those directories are added the server is ready to launch. Close the dialogues with OK and then launch the server by double clicking the entry "Illarion" on the left hand side. 3. Connecting to the server --------------------------- Once the server has started it will ask you for your login information. And if you tried this before reading the above steps then you will notice that you do not know the login data. That is because you are supposed to log in via SSH. Similar to the Illarion server this server is also accessed using SSH. The following information is relevant for the SSH connection. Server: localhost Port: 10022 User: user RSA key authentication using the illarion_local_rsa OpenSSH key. For the windows users this information is usually useless. For this reason the description for setting up PuTTy follows. Putty is an application to access the terminal of other computers. In this case it will be used to access the local server. First download PuTTy from their homepage: http://www.putty.org/ Once installation is complete launch it. You will now need to setup the connection to the local server. First set the hostname and the port for your connection. Host Name: localhost Port: 10022 Connection type: SSH Select the category "Window->Translation" and set the remote character set to: UTF-8 Select the category "Connection->Data" and set the Auto-login username to: user Also in this category, add an environment variable for your locale. The variable is LANG and the value can be de_DE.UTF-8, en_US.UTF-8 or en_GB.UTF-8 depending on your keyboard layout. Select the category "Connection->SSH->Auth" and browse for the private key file illarion_local.ppk which was delivered along with the server. Once all this is done get back to the "Session" category and enter a name like "Local Illarion Server" into Saved Session and then click [Save]. Now you can launch the session by double clicking your newly created session. 4. Updating the server ---------------------- Now one of the first things to do should be updating the server. You should also do this on a regular basis so your server keeps up with the development. You need an SSH connection to the server so have its command prompt open. Simply enter: ~/update And hit enter. The server will now update itself and the database. This will take some seconds. The steps of the update will be confirmed with OK. In case they are not OK, you should contact a developer. In case you only want to update the server or only the database you need to tell the update script. Use ~/update server or ~/update database The database is always a current copy of the server database excluding the character data. So you may update the database at any time to reflect the changes done to the online database onto your local database. However, you need to be aware that this will overwrite any changes you did to the local database. 5. Maintaining the server --------------------------- These steps shouldn't be required very often, but still you should know about them. There are a few scripts on the server that will help you to work with it. ~/start -> Launches the server program ~/stop -> Asks the server program to terminate, when it is convenient ~/kill -> Forcefully terminates the server program ~/reload -> Reloads the maps in the server program ~/status -> Prints he status of the server program You can start all those scripts by typing them into the command line of your SSH connection. 6. Script development --------------------- Reloading the scripts works on the server like on the normal server. You just hit the reload command (!fr) in the game and the server loads all the scripts. However, this server reads the scripts directly from your working copy of the scripts. This means you do not need to commit them in order to test them. You can simply save the files to the directory and make the server load them. You can commit whenever you feel a logical step has been accomplished, but push working states ONLY! You do need to commit and push the scripts in order to allow others to see and test your scripts. You can view the script error log and the script log in your browser: http://localhost/~illarion/script_error_log.php http://localhost/~illarion/script_log.php You can also use the unfiltered server log. Use e.g. the following command to view the log within your SSH console: less /var/log/illarion.log You can scroll with arrow keys, PgUp, PgDown, go to the top with G, to the bottom with Shift-G and start following automatically with Shift-F. To abort following the log hit Ctrl-C. 7. Database access ------------------ Use e.g. pgAdmin (http://www.pgadmin.org) to access the database from your OS. Hostname: localhost Port: 15432 You can also use phpPgAdmin within your browser, this is the same method we use for development on the official server: http://localhost/phppgadmin Login information: User: illarion Password: illarion 8. Connecting to the game ------------------------- Fire up the test client as usual. You can get the loader here: http://illarion.org/illarion/us_java_download.php You want to use the development client, so you need to adjust the update channel under "Options" accordingly. After launching the client, hit "Options" and select the server category. Server address: localhost Server port: 13000 Account login: disabled Save and go back to the login screen. Select the user-defined server. Now you can login with the default character: Name: Testserver One Password: test Of course you can add new characters to the database. 9. Using the local webserver ---------------------------- You can also use the local server for website development. For that you need to set up the website folder as described in step 2 prior to starting the VM. Also you need to make your system believe that the VM is actually illarion.local by editing your hosts config file. If you have no idea where that might be, here is an overview where you can find the location for your operating system: http://en.wikipedia.org/wiki/Hosts_(file)#Location_in_the_file_system Open the file with admin privileges and add a line at the end: 127.0.0.1 illarion.local When the VM is running you can now access your local copy of the website at http://illarion.local Log into the website with user test and password test. 10. Shutting down the server ---------------------------- Close the VM window and select shutdown with ACPI event. 11. Patches ---------------------------- The following patches have been applied to this build. They can be applied to older builds to keep them operational. Older build is available here: https://drive.google.com/folderview?id=0B-ZaHxrl0yMkfklqRDhQam11QnRxTk83b1J1NVY2eHY0OHQ0U0tWQUc1enZ3eldKV0Z2SXc 1) Log into your local server with putty 2) Write and submit: sudo nano /etc/apt/sources.list.d/illarion.list 3) A text editor will open, with text only on the first line. In front of all text on this line place a # 4) Save and close the file (Ctrl-X, press Y then and then enter) 5) Write and submit: sudo apt-get update 6) Write and submit: sudo apt-get install apt-transport-https 7) Confirm the question if installing is okay with: Y 8 ) Write and submit: sudo nano /etc/apt/sources.list.d/illarion.list 9) Remove the leading # that you have just added, save and quit again using Ctrl-X, Y, enter 10) Write and submit: sudo apt-get update 11) Update your local server as usual with ~/update The Debian release the local server is using (Jessie) was removed recently from their mirror network. It will only receive security-updates from now on. 1) Log into the local server via putty e.g. and type the following: 'sudo nano /etc/apt/sources.list'. An editor will open, showing you a file with two lines, a space, two lines, a space, two lines. 2) Change 'http://ftp.de.debian.org/debian/' into 'http://archive.debian.org/debian/'. 3) Also change in the third block "jessie-updates" into 'jessie-backports'. 4) Close the file using Control-X. Apply your changes by pressing Y if prompted. 5) Next type the following 'sudo nano /etc/apt/apt.conf': An empty editor will open. 6) Write the following: 'Acquire::Check-Valid-Until "false";' 7) Close the editor using Control-X. Apply your changes by pressing Y if prompted. 11) Update your local server as usual with ~/update. It should run normally (the first run may take a bit longer than usual). You do not need to repeat the step above for further updates.