Skip to content

Commit

Permalink
Add a "First Run" page, split Getting Started in separate pages
Browse files Browse the repository at this point in the history
  • Loading branch information
@aramperes
aramperes committed Apr 16, 2018
1 parent f5eb29e commit 1fb03e7
Show file tree
Hide file tree
Showing 6 changed files with 228 additions and 140 deletions.
86 changes: 86 additions & 0 deletions Getting_Started/first_run.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
First Run
#########

After having installed Glowstone for your operating system, you can start your server using the script you created.

.. tip::

If you want the server to simply generate/validate configuration files without starting the server, you can use the
:code:`--generate-config` command-line argument.

Simply add the argument at the end of the :code:`java [...] -jar glowstone.jar` line inside your startup script.

Console Output
==============

Server Version
--------------

Whenever you start the server, the first line will output the server version. For example:

.. code-block:: none
[INFO] This server is running Glowstone version 2018.4.0-SNAPSHOT.be008ff (MC: 1.12.2) (Implementing API version 1.12.2-R2.1-SNAPSHOT)
* The first information is the software version, :code:`2018.4.0-SNAPSHOT`. The :code:`SNAPSHOT` suffix is only present on development versions (i.e. not releases).
* The second part is a hash segment uniquely identifying the build you are using (:code:`be008ff`).
* In parentheses is the Minecraft version supported by the server (:code:`MC: 1.12.2`).
* Finally, the API version is the Glowkit_ version the server implements (:code:`1.12.2-R2.1-SNAPSHOT`).

.. _Glowkit: https://github.com/GlowstoneMC/Glowkit

Library Downloads
-----------------

When you first start the server, it will need to download some additional libraries from our repository
in order to keep compatibility with some plugins. This may take a few seconds depending on your internet connection.

.. code-block:: none
[INFO] Downloading org.apache.commons:commons-lang3:3.5...
[INFO] Downloaded org.apache.commons:commons-lang3:3.5.
[ etc. ]
More information about libraries can be found in the `Library Management`_ section.

Plugin Scanning
---------------

Your server will then scan for plugins inside the :code:`plugins` directory. Once it finds compatible plugins,
they will be loaded before the worlds are loaded. If you are familiar with Bukkit plugin development, this is
the time when the :code:`JavaPlugin#onLoad()` method is executed.

World Generation/Loading
------------------------

The server will load world files from disk, located by default in the :code:`worlds` directory.
If it can't find a world, it will create it and start generating the terrain. Again,
this may take a while depending on your hardware.

.. code-block:: none
[INFO] Preparing spawn for world...
[INFO] Preparing spawn for world: 0%
[INFO] Preparing spawn for world: 2%
[INFO] Preparing spawn for world: 6%
[ etc. ]
[INFO] Preparing spawn for world: done
Plugin Enabling
---------------

After the worlds are loaded and ready, the plugins that were previously loaded are now "enabled".

Server Binding
--------------

Once it is ready, the server will open itself on a TCP port. By default, this is port :code:`25565`, and can be
changed in the server configuration. For more information, refer to the `Configuration Guide`_ section.

.. code-block:: none
[INFO] Binding server to 0.0.0.0:25565...
[INFO] Successfully bound server to 0.0.0.0:25565.
[INFO] Ready for connections.
Once the "Ready for connections." line is output, your server should be reachable by clients.
148 changes: 9 additions & 139 deletions Getting_Started/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,136 +1,21 @@
Getting Started
#######################

Glowstone Installation
************************

Installing Glowstone is as easy as installing any other server software.

Install Java
===============

Install `Oracle Java 8`_ (recommended).
If you're running a Linux distro, look into installing Oracle Java through your package manager before using these downloads.
But, if you really don't want Oracle Java, you can use OpenJDK_.

.. note::

**We require Java 8 update 101 or greater.**

Our Maven repository uses a Let's Encrypt HTTPS certificate, and Let's Encrypt was added to the Java truststore in update 101.

Without this truststore, our library manager fails to pull dependencies from our server, due to an SSL security error.

Confirm that you have Java 8 by running :code:`java -version` in your system's command prompt/terminal.
You should see something like :code:`java version "1.8.0_121"` at the top. As long as it includes :code:`1.8`, and the number after the :code:`_` is more than 101, you're good.


.. note::

If you installed Java 8 on **macOS**, but :code:`java -version` is showing an older version, run

.. code-block:: sh
sudo mv /usr/bin/java /usr/bin/java-1.6
sudo ln -s '/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java' /usr/bin/java
For more details, see `this guide`_.


.. _Oracle Java 8: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html
.. _OpenJDK: http://openjdk.java.net/install/
.. _this guide: https://gist.github.com/johan/10590467


Install Glowstone
====================

1. Download the latest build of Glowstone_.
2. Move the jar file to your server folder. If you drop and run the jar in your current server folder, it will automatically migrate most settings to Glowstone.
3. Follow the instructions for your operating system below.

.. _Glowstone: https://glowstone.net/#downloads

Windows
--------

Using a text editor like Notepad, create a new start script named :code:`start.bat` to launch the jar file:

.. code-block:: bat
@echo off
java -Xms768M -XX:+UseG1GC -jar glowstone.jar
pause
Make sure you select :code:`All Files` as the file type in the save window.

Finally, double click the :code:`start.bat` file.

GNU/Linux
----------

Using a text editor like gedit, mousepad, Atom, Sublime Text, nano, (Neo)vi(m), Kate or emacs, create a new start script named :code:`start.sh` to launch the jar file:

.. code-block:: sh
#!/bin/sh
BINDIR=$(dirname "$(readlink -fn "$0")")
cd "$BINDIR"
java -Xms768M -XX:+UseG1GC -jar glowstone.jar
Open terminal, go to your Glowstone folder and enter this command to give the script execute permissions:
.. toctree::
:maxdepth: 2
:caption: Contents
:titlesonly:

.. code-block:: sh
install_java
install_glowstone
first_run
plugins

chmod +x start.sh
Enter this command in the terminal to start the server:

.. code-block:: sh
./start.sh
macOS
------

Using a text editor like TextEdit, create a new start script named :code:`start.command` to launch the jar file:

.. code-block:: sh
#!/bin/bash
cd '$( dirname "$0" )'
java -Xms768M -XX:+UseG1GC -jar glowstone.jar
Open terminal, change current directory by typing :code:`cd` and dragging and dropping the Glowstone folder into terminal window.

At this point it should look like this:

.. code-block:: sh
cd /Users/YourName/YourGlowstoneFolder/Glowstone
If you think that is correct press enter and move to the next step.

Just **type** (do not enter!) this command to give the script execute permissions:

.. code-block:: sh
chmod a+x
Drag start.command into the Terminal window. Confirm there is a space between :code:`chmod a+x` and the :code:`start.command` path, and then enter.
Finally, double click the :code:`start.command` file to start the server.


After Thoughts
================

If you have any trouble setting up, we would be happy to help you on the forums_
or Discord_. Otherwise, congratulations! You've just installed Glowstone!
or Discord_.

* If you can't access your server from your public IP, make sure you have `port forwarded`_ or used a UPnP port mapper to allow incoming connections to your server.
* For server issues or suggestions, create an issue on Github.
Expand All @@ -139,18 +24,3 @@ or Discord_. Otherwise, congratulations! You've just installed Glowstone!
.. _forums: https://forums.glowstone.net/
.. _Discord: https://discord.gg/TFJqhsC
.. _port forwarded: http://portforward.com/english/applications/port_forwarding/Minecraft_Server/

Plugins
************

Most Bukkit_, Spigot_ and Paper_ plugins will work on Glowstone.

.. warning::

Plugins that use internals for Paper, Spigot, CraftBukkit, or Minecraft will not work, unless they are designed to fail gracefully.

This includes plugins that use "*NMS*" reflectively.

.. _Bukkit: http://dev.bukkit.org/bukkit-plugins/
.. _Spigot: https://www.spigotmc.org/resources/categories/bukkit.4/
.. _Paper: https://aquifermc.org/resources/categories/server-plugins.2/
81 changes: 81 additions & 0 deletions Getting_Started/install_glowstone.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
Install Glowstone
=================

1. Download the latest build of Glowstone_.
2. Move the jar file to your server folder. If you drop and run the jar in your current server folder, it will automatically migrate most settings to Glowstone.
3. Follow the instructions for your operating system below.

.. _Glowstone: https://glowstone.net/#downloads

Windows
-------

Using a text editor like Notepad, create a new start script named :code:`start.bat` to launch the jar file:

.. code-block:: bat
@echo off
java -Xms768M -XX:+UseG1GC -jar glowstone.jar
pause
Make sure you select :code:`All Files` as the file type in the save window.

Finally, double click the :code:`start.bat` file.

GNU/Linux
---------

Using a text editor like gedit, mousepad, Atom, Sublime Text, nano, (Neo)vi(m), Kate or emacs, create a new start script named :code:`start.sh` to launch the jar file:

.. code-block:: sh
#!/bin/sh
BINDIR=$(dirname "$(readlink -fn "$0")")
cd "$BINDIR"
java -Xms768M -XX:+UseG1GC -jar glowstone.jar
Open terminal, go to your Glowstone folder and enter this command to give the script execute permissions:

.. code-block:: sh
chmod +x start.sh
Enter this command in the terminal to start the server:

.. code-block:: sh
./start.sh
macOS
-----

Using a text editor like TextEdit, create a new start script named :code:`start.command` to launch the jar file:

.. code-block:: sh
#!/bin/bash
cd '$( dirname "$0" )'
java -Xms768M -XX:+UseG1GC -jar glowstone.jar
Open terminal, change current directory by typing :code:`cd` and dragging and dropping the Glowstone folder into terminal window.

At this point it should look like this:

.. code-block:: sh
cd /Users/YourName/YourGlowstoneFolder/Glowstone
If you think that is correct press enter and move to the next step.

Just **type** (do not enter!) this command to give the script execute permissions:

.. code-block:: sh
chmod a+x
Drag start.command into the Terminal window. Confirm there is a space between :code:`chmod a+x` and the :code:`start.command` path, and then enter.
Finally, double click the :code:`start.command` file to start the server.
35 changes: 35 additions & 0 deletions Getting_Started/install_java.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
Install Java
============

Install `Oracle Java 8`_ (recommended).
If you're running a Linux distro, look into installing Oracle Java through your package manager before using these downloads.
But, if you really don't want Oracle Java, you can use OpenJDK_.

.. note::

**We require Java 8 update 101 or greater.**

Our Maven repository uses a Let's Encrypt HTTPS certificate, and Let's Encrypt was added to the Java truststore in update 101.

Without this truststore, our library manager fails to pull dependencies from our server, due to an SSL security error.

Confirm that you have Java 8 by running :code:`java -version` in your system's command prompt/terminal.
You should see something like :code:`java version "1.8.0_121"` at the top. As long as it includes :code:`1.8`, and the number after the :code:`_` is more than 101, you're good.


.. note::

If you installed Java 8 on **macOS**, but :code:`java -version` is showing an older version, run

.. code-block:: sh
sudo mv /usr/bin/java /usr/bin/java-1.6
sudo ln -s '/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java' /usr/bin/java
For more details, see `this guide`_.


.. _Oracle Java 8: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html
.. _OpenJDK: http://openjdk.java.net/install/
.. _this guide: https://gist.github.com/johan/10590467
16 changes: 16 additions & 0 deletions Getting_Started/plugins.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
Plugins
=======

Most Bukkit_, Spigot_ and Paper_ plugins will work on Glowstone.

As you would with a CraftBukkit server, place the plugin :code:`.jar` files inside the :code:`plugins` directory.

.. warning::

Plugins that use internals for Paper, Spigot, CraftBukkit, or Minecraft will not work, unless they are designed to fail gracefully.

This includes plugins that use "*NMS*" reflectively.

.. _Bukkit: http://dev.bukkit.org/bukkit-plugins/
.. _Spigot: https://www.spigotmc.org/resources/categories/bukkit.4/
.. _Paper: https://aquifermc.org/resources/categories/server-plugins.2/
2 changes: 1 addition & 1 deletion index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,5 +24,5 @@ Table of Contents
.. toctree::
:maxdepth: 2

Getting_Started/index
Why_Glowstone/index
Getting_Started/index

0 comments on commit 1fb03e7

Please sign in to comment.