mnubottomshadow



INSTALL OPENSIM SERVER FROM SOURCE.


What follows is a complete example installation of an OpenSim server, beginning from the OpenSim server source code.

Prerequisites-Assumptions:

1. Tortoise SVN client
2. MySQL
3. Hippo viewer
4. Windows 7 - Earlier versions may be OK, but we have not tried them.



The basic steps are:

1) Download the OpenSim server source code
2) Compile the OpenSim server source code
3) Copy the OpenSim\Source\bin directory to the OpenSim\Prod directory
4) Edit the OpenSim.ini.example.txt file to create an OpenSim.ini file
5) Set up a MySQL database for the OpenSim server data
6) Define the correct MySQL database user - matching the user from the .ini file
7) Start opensim.exe - it should complete its own installation, but ...
8) Answer the startup questions for the initial (installation) run of opensim.exe
9) Connect to the new OpenSim server using the Hippo viewer

What worked for us.

Just so you know, when we did all of this, we were not Open Source gurus - just a couple of Joes trying to have a good time. We had to search through quite a few earlier examples (thanks to the earlier posters who helped us out) that are no longer quite current. Our own process is dated late November, 2009. We expect others to make new posts once ours has gone stale.

Also, the hard parts for us were: 1) getting the correct download to start with, and 2) defining the correct MySQL database user. That is how we wound up with Toad and Tortoise. Everything else worked very well on the first or second try - though the startup questions spooked us a bit. Connecting the Hippo viewer was pretty easy - mostly because we had done binary installations earlier, I think. YMMV.

The full example that is shown below is for a Windows 7 system. This example gets the OpenSim server running as a standalone, local-only server.

Expect to do this at least twice. Treat this installation not only as a voyage of discovery (which it will be for almost all of you), but also as training. If you stay with the project for long, there will be more OpenSim server installations in your future. That second (or third or fourth ...) installation helps you to absorb the details more deeply - and to accept the inevitible overhead of maintaining an open source system such as OpenSim server.

Once your first server is up and running, you have virtually no investment in the process. Set yourself up in another directory and install it all over again. It is really not so bad the second time around, and it will improve your confidence for future tasks as you see how the major parts interoperate and how names and IDs link the system components together.


STEP ZERO. Get and install Tortoise. Get and install MySQL. You will also want to have the Hippo viewer ready to go. We suggest that you have used Hippo to connect to another grid, just to make sure that it is installed correctly and functioning.

STEP ONE. Download the OpenSim server source code


1.1 Create a directory called OpenSim. In this example, the source code is going to wind up in the Source subdirectory under OpenSim, and the production server (exe file, ini file, etc.) is going to wind up in the Prod/bin directory under OpenSim. If you use different names and different directory structures, do not come crying to us. We are not entirely insensitive, though. You can put the OpenSim directory anywhere you want. We put ours off of the root directory of the C: drive. You would be wise to do the same. We are just saying . . . Wise.

1.2 Because you already installed Tortoise, the next step is really easy. Open Windows Explorer (not Internet Explorer) so that you can see the Opensim directory. Right click on the OpenSim directory icon and select "SVN Checkout..." from the dialog box.

1.3 Tortoise presents you with a "Checkout" dialog box.

1.3.1 In the "URL of repository:" box enter
http://opensimulator.org/svn/opensim-track/trunk


1.3.2 In the "Checkout directory:" box enter
C:\OpenSim\Source


Now you see the path of wisdom. If you did not put OpenSim where we suggested, you cannot follow this direction exactly and get correct results. You are not screwed, exactly - but you are on your own from this point forward. Good luck making all of the translations required for the remainder of this example.

1.3.3 Leave/Set the "Checkout depth" entry as "Fully recursive" , and leave/set the "Revision" entry with the selection "HEAD revision" . Here's a picture:



1.3.4 Click OK.

The download should run to completion. At the end, you should have a Source directory containing 10 directories and 12 files. That's what we got anyway - 2325 files totaling 34.45 megabytes. Here's evidence we're telling the truth:



STEP TWO. Compile the OpenSim server source code. You do this from the command line, so ...

2.1 Open up a Command Prompt window and enter the command
cd c:\OpenSim\Source


2.2 Run the runprebuild.bat file. Among other things, runprebuild.bat creates the file compile.bat.

2.3 Run the compile.bat file. The compile output is very chatty, but at the end you should see the message that there were 49 warnings and no erors.

NOTE: You can also use some variation of Visual Studio that compiles C#, and we have done that, too. But for the first-time installation, use the batch file.

STEP THREE. Copy the C:\OpenSim\Source\bin directory to the C:\OpenSim\Prod directory.

3.1 The result of the compilation in STEP TWO is a fully populated C:\OpenSim\Source\bin subdirectory. Copy the C:\OpenSim\Source\bin directory (the whole directory, not just the contents) to the C:\OpenSim\Prod directory. The result of the copy is that you have a fully populated C:\OpenSim\Prod\bin subdirectory.

Those of you who were not so wise (see step 1.1 above), are now facing a deeper and deeper pile of adjustments in directory names. It's not too late, just erase everything that you have done so far and start over. As you can see, in 10 or 20 minutes you'll be right back here, feeling the wisdom flow through you. Wisdom, yeah. Feels good.

STEP FOUR. Edit the OpenSim.ini.example.txt file to create an OpenSim.ini file.

4.1 You will make just a few changes in the [Startup] section and a few changes in the [StandAlone] section.

4.2 In the [Startup] section, find the line that identifies the storage sub-section by searching for the string "## STORAGE". The task here is two-fold: first, to switch from sqlite to MySQL; second, to identify the database user that OpenSim server will rely on to make its database connection.

4.3 Put semicolons in front of the sqlite lines for storage_plugin and storage_connection_string. Remove the semicolons for the MySQL lines.

4.4 Replace the Source, Database, UserID and Password entries in the MySQL storage_connection_string line with the name of your computer, your user name and password. A finished replacement line would look something like this:

storage_connection_string="Data Source=OldBlue;Database=LJsim;User ID=tinker;Password=miriam;";


for a user named 'tinker' with password 'miriam' on a computer named 'OldBlue'. See step 5.1 below for instructions for finding your computer name.

That almost-doubled semicolons at the end is correct. Don't ask us why. We don't know. But it works. Well, we think we know, but the main thing is that it looks like it could be a mistake, but it is not.

NOTE: The connection string is the same in all three locations. Get it right once, then copy it in the other two spots.

And a couple of caveats here: The password will be sitting in this .ini file in plain text for as long as you are running OpenSim server. Seems dangerous, but for now it's not a problem because we are creating a network-isolated, standalone server. Second, we don't really know the requirements for the user - what access rights he needs, or what roles he has to have, or any of that stuff. We just created a new administrator user and put him in there. To be honest, though, that password still makes us queasy. You may want to create a separate user just for the purpose of managing the MySQL database for the OpenSim server and work on trimming his access rights and system role over time.

4.5 In the [StandAlone] section, the changes are similar. For the lines that start with

inventory_plugin,

inventory_source,

userDatabase_plugin, and

user_source

comment out the sqlite entries with semicolons and enable the MySQL entries by removing the semicolons.

4.6 On the inventory_source line and the user_source line, put in the same Source, Database, User ID and the same password that you entered previously. All of the same caveats apply.

4.7 BONUS OPPORTUNITY. This is a totally unnecessary step, but it does have some use. You may customize the welcome_message line. Ours looks like this:

welcome_message = "***** Welcome to The Lovejoy Project OpenSimulator *****"


This is useful because the server displays this message when you login with the Hippo viewer. It confirms that the server is using *your* configuration file.

4.8 Save the edited file as opensim.ini.

And a brief note here: You may have noticed that the file name is "opensim.ini" in step 4.8, but "OpenSim.ini" in the STEP FOUR header line. Hey, it's Windows, and we can get away with it. Just one more reason to recognize that these instructions do not work (in detail) in other environments.

STEP FIVE. Set up a MySQL database for the OpenSim server data.

NOTE: Linking up to MySQL turned out to be the most troublesome aspect of the installation for us.

The basic installation of MySQL, we leave to others. Once you have MySQL installed, though, here's how we finally successfully set up MySQL to work with OpenSim server.

Define a user for MySQL. The user that you define for MySQL should be a Windows user with sufficient file privileges to create files.

We did the MySQL installation of version 5.1 which put a "MySQL command line client" on our system. So we start MySQL by clicking on that client. You need to create a user, and grant him all rights to the database.

5.1 Determine the name of your computer. Click the Windows START button, then right-click "Computer" on the Start menu, then select Properties. Under the heading "Computer name, domain, and workgroup settings" you will see the computer name. In our case that name is "OldBlue".


5.2 Get to a MySQL prompt. Then enter the following commands:

mysql> connect mysql;

mysql> create user tinker@OldBlue identified by 'miriam';

mysql> grant all on *.* to tinker@OldBlue;

Now you should have a user that shows up like this:


mysql> select user,host from user;
+--------+-----------+
| user | host |
+--------+-----------+
| root | 127.0.0.1 |
| tinker | OldBlue |
| root | localhost |
+--------+-----------+
3 rows in set (0.00 sec)

To be clear:

The "tinker" entry in the MySQL listing above is the account name of a Windows user, and it is the value that goes into the "User ID=xxxxxxx" clause in the opensim.ini file.

And the "OldBlue" entry in the MySQL listing above is the name of the Windows 7 computer, and it is the value that goes into the "Data Source=xxxxxx" clause in the opensim.ini file.

And the Windows 7 password for the user "tinker" should be the password that you use when you create the MySQL user; and it is the same password that you put into the "Password=xxxxxx" clause in the opensim.ini file.


That's it. There may be other paths to get here. Certainly you may already have defined users in a pre-existing MySQL installation. If so, make sure that one of those users with sufficient Windows privileges and with sufficient MySQL privileges is the one that you use when you modify the opensim.ini file.

5.3 Create the opensim starter database before you run the OpenSim server.

mysql> create database LJsim;


STEP SIX. Define the correct MySQL database user - matching the user from the .ini file

NOTE: This step caused us quite a bit of grief. The short form of the advice is to be very careful about matching up your MySQL user of the MySQL database with the user named in the opensim.ini file.

First, you need a Windows user that has write access to the OpenSim directories. For us that was the new user we defined when we set up for this example - tinker.

Second,that user needs a password. Tinker's password was "miriam".

In the opensim.ini file, for the MySQL database settings, put your computer name in place of "localhost" - BUT ONLY in the MySQL database lines. The string "localhost" occurs throughout the opensim.ini file, and you do not want to replace any other occurrences with your computer name.

In the same lines where you replace "localhost" with your computer name, put the name of your MySQL database in place of the "opensim in the clause "Database=opensim". And put your selected user name in place of the user name "opensim" in the clause "User ID=opensim". And put your user's password in place of the asterisks in the "Password=*****" clause.

This is what one of those lines looks like with the computer name "OldBlue", user name "tinker" and password "miriam" put in place:

storage_connection_string="Data Source=OldBlue;Database=LJsim;User ID=tinker;Password=miriam";


STEP SEVEN. Start opensim.exe - it should complete its own installation, but ...

7.1 Open a Command Prompt window and execute the command
>cd c:\OpenSim\Prod\bin


7.2 Enter the command
>opensim


That's it. The server should start up, spit out a potload of trace/status info - and then stop dead with a question staring out at you from the console . . .

STEP EIGHT. Answer the startup questions for the initial (installation) run of opensim.exe

8.1 Name the Sim.

8.2 "Zero user" fist name.

8.3 "Zero user" last name.

8.4 "Zero user" password.

8.5 The full dialog is shown below.

=====================================

We are now going to ask a couple of questions about your region.

You can press 'enter' without typing anything to use the default

the default is displayed between [ ]: brackets.
=====================================

New region name []: LJsim
Region UUID [c3f38760-9cf3-4bef-a5bb-d5abd26c8687]:
Region Location [1000,1000]:
Internal IP address [0.0.0.0]:
Internal port [9000]:
Allow alternate ports [False]:
External host name [SYSTEMIP]:
Master Avatar UUID [00000000-0000-0000-0000-000000000000]:
Master Avatar first name (enter for no master avatar) []: Tinker
Master Avatar last name []: Tinker
Master Avatar sandbox password []:xxxxxx


NOTE: Most of the questions can be answered simply by accepting the default. The dialog will accept null values for the "Master Avatar" first and last names (or either one), but you cannot logon in the Hippo viewer without both a first and last name. If you screw this up, you can define a user via the "create user" command on the server console. We don't know whether that is a good substitute for getting this dialog done right in the first place.

It is probably better to do what we did: 1) drop the database in MySQL and create it again; 2) save your OpenSim.ini file; 3) delete the Prod\bin directory; 4) copy the Source\bin directory to Prod again; 5) copy the saved OpenSim.ini file back into the Prod\bin directory; and 6) run opensim.exe again and get the dialog right.

When you type in the password, it shows up in clear text on the console.

STEP NINE. Connect to the new OpenSim server using the Hippo viewer.

9.1 "Add" a grid.

9.2 Enter a nickname = Lovejoy Sim

9.3 Address = http://localhost:9000

9.4 User First Name

9.5 User Last Name

9.6 User Password


In conclusion . . .

In the process of putting these instructions together and checking them for accuracy (not completeness - they are far from complete), we did multiple installations and re-installations of OpenSim server. At the end, starting from scratch, i.e., with Hippo and Tortoise and MySQL already installed, we could follow these steps and be up and running in about 20 minutes.

We trimmed this back to as basic an installation as we could muster. We took out all of the network and Internet issues and all of the OS and database variations. No routers, no firewalls, no DNS, no Linux, no sqlite, no Mac, no Vista - none of that stuff. Because this is not just local, it's for use by a single user on a single machine - valid in detail only for the Windows 7 operating system and MySQL. That's as low as you can go and still get any benefit from OpenSim server.

But it is a start, a stable position from which you can build more elaborate, more accessible worlds. Once you get here, you have a solid position from which you can reach out to the rest of the world - and worlds. This is your fulcrum - fixed and immovable - that allows you to make and move worlds.

Still, gremlins and goblins lurk in every installation. Malevolent forces, acting alone or in concert, stand between you and a clean install. Environment variables, .NET framework, user access rights, and a whole host of other variations from one system to the next can thwart even the wise, literal follower of this one sure ("sure," not "true") path. When that happens - we can't help you. Too much detail, too much distance, imprecise communication, lack of shared background, not enough knowledge. We just can't do it.

Our best advice is: If at first you don't succeed, try, try again. That's how we did it.

This entry is a contribution of LS Divvy and LS Tinker at the LovejoySim Project.