Install notes.

1 files changed, 228 insertions, 0 deletions

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..40bf35b
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,228 @@
+Use this to create a sim that links into IG or MG grids from Linux.  Or
+to run your own grid.
+
+It's only been tested on Ubuntu 10.04, 11.04, 12.04, 16.04, as well as
+Debian 8, Devuan 9, and Devuan 9.  YMMV.  This is also a WIP, use it at
+your own risk.  It's been used to set up a few freshly installed servers
+though.  It should work on recent Debian based Linux distros.
+
+You may want to use the latest Mono, you can get it by following the
+instructions at -
+
+https://www.mono-project.com/docs/getting-started/install/linux/
+
+
+For those in a hurry.
+---------------------
+
+On a recent Debian based Linux (Debian, Devuan, Ubuntu, Mint, ...)
+terminal, run the following command -
+
+./InstallItAll.sh
+
+This will install the prerequisites (MariaDB, monit, MONO, tmux,
+uuid-runtime); create a database in MariaDB called opensim_SC and a
+database user called opensim_SC with a random password; add a Linux user
+and group to your system called opensimsc; create the /opt/opensim_SC
+directory to run it all from; copy everything to
+/opt/opensim_SC/opensim-SC_0.9.0.1; setup the directory structure needed
+to run it all; create some default configuration files; build opensim-SC;
+and finally change ownership and file permissions for everything.
+
+You will likely need to login your user again, so you get the new group
+assigned to it.  Otherwise the tmux stuff in start-sim might fail.
+
+Next go to /opt/opensim_SC/current/scripts/install and run -
+
+sudo ./create_sim.sh
+
+This will create a randomly named sim at a randomly chosen position.  Or
+for something less random -
+
+sudo ./create_sim.sh "My new sim" "1234,5678"
+
+At this point /opt/opensim_SC/config/config.ini will be a symlink
+pointing to config_localhost.ini, which is for a standalone sim.  If you
+want your new random sim to be part of IG or MG grids then you'll have to
+change that syml/ink to point to config_IG.ini or config_MG.ini
+respectively.  There is no point doing that unless you are a member of
+those grids.
+
+/opt/opensim_SC/config/sim01 now contains the actual configuration of
+your randomly created sim.  Edit the .ini file to make that sim a little
+less random.  You can even rename the .ini file to match your sim name.
+
+If you are running a grid run -
+
+cd /opt/opensim_SC/config/ROBUSH
+./start-sim
+
+Then to actually startup your sim -
+
+cd /opt/opensim_SC/config/sim01
+./start-sim
+
+And if you want to see the console of your sim run -
+
+cd /opt/opensim_SC/current/scripts
+./show-console
+
+
+The directory layout.
+---------------------
+
+The various directories are -
+
+.git            Used by git for it's internal accounting, and the older versions.
+
+.nant           Used by the obsolete nant build tool.
+
+OpenSim         OpenSim source code.
+
+Prebuild        Used by the build system.
+
+ThirdParty      For third party OpenSim modules.
+ThirdPartyLicenses
+
+addon-modules   Also for third party modules.  Don't ask me why there's two.
+
+bin             The OpenSim binaries, and other files.
+
+doc             Supposedly for documentation, which I wish OpenSim devs would write some.
+
+example         An example of how to set this all up.
+
+scripts         Various Linux scripts for managing OpenSim.
+
+share           No idea really.
+
+Also, the installation script copies the following directories from the
+example directory, to outside of this main directory, they are all used
+for writing various things.  Makes it easy to upgrade, and separates them
+from actual executable stuff.
+
+AssetFiles      Stores assets if running in grid mode.
+
+backups         All sim and inventory backups are stored here.
+
+caches          Various cached things.
+
+config          All your configuration files.
+
+db              If you are not using MySQL, your data lives here.
+
+logs            Log files get stored here.
+
+web             Web files go here.  You can edit them to change the background image for example.
+
+
+Follow these steps.
+-------------------
+
+First you need to have a user on your computer with sudo access.
+
+Next you need to figure out what password you want to use for OpenSims
+access to the database.  We will call this "DatabasePassword".  Run the
+following script, from inside the OpenSim directory -
+
+./InstallItAll.sh DatabasePassword
+
+This will do most of the work for you, except for creating sims.
+
+
+Creating sims.
+--------------
+
+A separate script is here for sim creation, you can use it to create many
+sims.  You will need -
+
+A name for your sim, we will use "My new sim".  It should be unique on
+the grid.
+
+A location for your sim, we will use "1234,5678".  Choose an empty spot.
+
+Once you have all that information sorted out, run this script from the
+scripts/install directory -
+
+./create_sim.sh "My new sim" "1234,5678" "sims.example.net"
+
+Also, you can create a varregion with something like -
+
+./create_sim.sh "My new sim" "1234,5678" 512
+
+Note that the size has to be a multiple of 256, so 512, 768, 1024, etc. 
+8096 is the maximum size, 2048 is about the biggest that is decently
+manageable.
+
+
+Running ROBUST.
+---------------
+
+If you are running your own grid, you need to start up ROBUST, which is
+a bunch of common services sims use.  Go to /opt/opensim_SC/config/ROBUST
+and run the following script to start it up -
+
+./start-sim
+
+You will see the tmux console.  You can run the tmux console again by
+running that command once more, or running the show-console script.
+
+
+Running sims.
+-------------
+
+Now you can go to /opt/opensim_SC/config/sim01 and run the following script
+to start it up -
+
+./start-sim
+
+You will see the tmux console.  You can run the tmux console again by
+running that command once more, or running the show-console script.
+
+You can stop the sim with -
+
+./stop-sim
+
+You can backup the sim with -
+
+./backup-sim
+
+
+Running it all at once.
+-----------------------
+
+You don't have to run ROBUST, then each sim, you can run the lot at once.
+Go to /opt/opensim_SC/current/scripts and run -
+
+./start-sim
+
+It'll wait a minute between sims to give things time to settle down, and
+not over work your computer.
+
+
+Finishing up.
+-------------
+
+Once it's all tested, you can use this to finish things off (back in
+the /opt/opensim_SC/current/scripts directory) -
+
+./go_live.sh
+
+Which sets up the monit control file/s, though you should double check
+it all, and you still have to do the basic configuration and enabling of
+monit yourself.  This is in case you already have monit set the way you
+like.
+
+This step is entirely optional, and some versions of monit might not work
+so well.
+
+
+NOTES -
+
+This attempts to use only one copy of the OS install for all sims.  We
+are running one instance of OS for each sim though, as this prevents one
+sim crashing from bringing down the others.  OS however really wants to
+write data to directories within it's own bin directory.  The preferred
+way to update opensim-SC is to download a fresh copy, run BuildIt.sh,
+delete the installed copy, then copy this new one to where the old one
+used to be.  I'll write an update script in the next version.