github.com/Azareal/Gosora@v0.0.0-20210729070923-553e66b59003/README.md (about)

     1  # Gosora ![Build Status](https://travis-ci.org/Azareal/Gosora.svg?branch=master) [![Azareal's Discord Chat](https://img.shields.io/badge/style-Invite-7289DA.svg?style=flat&label=Discord)](https://discord.gg/eyYvtTf)
     2  
     3  A super fast forum software written in Go. You can talk to us on our Discord chat!
     4  
     5  The initial code-base was forked from one of my side projects, but has now gone far beyond that. We've moved along in a development and the software should be somewhat stable for general use.
     6  
     7  Features may break from time to time, however I will generally try to warn of the biggest offenders in advance, so that you can tread with caution around certain commits, the upcoming v0.1 will undergo even more rigorous testing.
     8  
     9  File an issue or open a topic on the forum, if there's something you want and you very well might find it landing in the software fairly quickly.
    10  
    11  For plugin and theme developers, things are a little dicier, as the internal APIs and ways of writing themes are in constant flux, however some stability in that area should be coming fairly soon.
    12  
    13  If you like this software, please give it a star and give us some feedback :)
    14  
    15  If you dislike it, please give us some feedback on how to make it better! We're always looking for feedback. We love hearing your opinions. If there's something missing or something doesn't look quite right, don't worry! We plan to add many, many things in the run up to v0.1!
    16  
    17  
    18  # Features
    19  Standard Forum Functionality. All of the little things you would expect of any forum software. E.g. Common Moderation features, modlogs, theme system, avatars, bbcode parser, markdown parser, report system, per-forum permissions, group permissions and so on.
    20  
    21  Custom Pages. There are some rough edges
    22  
    23  Emojis. Allow your users to express themselves without resorting to serving tons upon tons of image files.
    24  
    25  In-memory static file, forum and group caches. We have a slightly more dynamic cache for users and topics.
    26  
    27  A profile system, including profile comments and moderation tools for the profile owner.
    28  
    29  A template engine which compiles templates down to machine code. Over forty times faster than the standard template library `html/templates`, although it does remove some of the hand holding to achieve this. Compatible with templates written for `html/templates`, so you don't need to learn any new templating language.
    30  
    31  A plugin system. We have a number of APIs and hooks for plugins, however they're currently subject to change and don't cover as much of the software as we'd like yet.
    32  
    33  A responsive design. Looks great on mobile phones, tablets, laptops, desktops and more!
    34  
    35  Other modern features like alerts, likes, advanced dashboard with live stats (CPU, RAM, online user count, and so on), etc.
    36  
    37  
    38  # Requirements
    39  
    40  Go 1.13 or newer - You will need to install this. Pick the .msi, if you want everything sorted out for you rather than having to go around updating the environment settings. https://golang.org/doc/install
    41  
    42  For Ubuntu, you can consult: https://tecadmin.net/install-go-on-ubuntu/
    43  You will also want to run `ln -s /usr/local/go/bin/go` (replace /usr/local with where ever you put Go), so that go becomes visible to other users.
    44  
    45  If you followed the instructions above, you can update to the latest version of Go simply by deleting the `/go/` folder and replacing it with a `/go/` folder for the latest version of Go.
    46  
    47  Git - You may need this for downloading updates via the updater. You might already have this installed on your server, if the `git` commands don't work, then install this. https://git-scm.com/downloads
    48  
    49  MySQL Database - You will need to setup a MySQL Database somewhere. A MariaDB Database works equally well and is much faster than MySQL. You could use something like WNMP / XAMPP which have a little PHP script called PhpMyAdmin for managing MySQL databases or you could install MariaDB directly.
    50  
    51  Download the .msi installer from [MariaDB](https://mariadb.com/downloads) and run that. You may want to set it up as a service to avoid running it every-time the computer starts up.
    52  
    53  Instructions on how to set MariaDB up on Linux: https://downloads.mariadb.org/mariadb/repositories/
    54  
    55  We recommend changing the root password (that is the password for the user 'root'). Remember that password, you will need it for the installation process. Of course, we would advise using a user other than root for maximum security, although that adds additional steps to the process of getting everything setup.
    56  
    57  You might also want to run `mysql_secure_installation` to further harden (aka make it more secure) MySQL / MariaDB.
    58  
    59  If you're using Ubuntu, you might want to look at: https://www.itzgeek.com/how-tos/linux/ubuntu-how-tos/install-mariadb-on-ubuntu-16-04.html
    60  
    61  It's entirely possible that your host already has MySQL installed and ready to go, so you might be able to skip this step, particularly if it's a managed VPS or a shared host. Or they might have a quicker and easier method of setting up MySQL.
    62  
    63  
    64  # How to download
    65  
    66  For Linux, you can skip down to the Installation section as it covers this.
    67  
    68  On Windows, you might want to try the [GosoraBootstrapper](https://github.com/Azareal/GosoraBootstrapper), if you can't find the command prompt or otherwise can't follow those instructions. It's just a matter of double-clicking on the bat file there and it'll download the rest of the files for you.
    69  
    70  # Installation
    71  
    72  Consult [installation](https://github.com/Azareal/Gosora/blob/master/docs/installation.md) for instructions on how to install Gosora.
    73  
    74  # Updating
    75  
    76  Consult [updating](https://github.com/Azareal/Gosora/blob/master/docs/updating.md) for instructions on how to update Gosora.
    77  
    78  
    79  # Running the program
    80  
    81  *Linux*
    82  
    83  If you have setup a service, you can run:
    84  
    85  `./pre-run-linux`
    86  
    87  `service gosora start`
    88  
    89  You can then, check Gosora's current status (to see if it started up properly) with:
    90  
    91  `service gosora status`
    92  
    93  And you can stop it with:
    94  
    95  `service gosora stop`
    96  
    97  If you haven't setup a service, you can run `./run-linux`, although you will be responsible for finding a way to run it in the background, so that it doesn't close when the terminal does.
    98  
    99  One method might be to use: https://serverfault.com/questions/34750/is-it-possible-to-detach-a-process-from-its-terminal-or-i-should-have-used-s
   100  
   101  *Windows*
   102  
   103  Run `run.bat`, e.g. double-clicking on it.
   104  
   105  
   106  # How do I install plugins?
   107  
   108  For the default plugins like Markdown and Helloworld, you can find them in the Plugin Manager of your Control Panel. For ones which aren't included by default, you will need to drop them down in the `/extend/` directory.
   109  
   110  You will then need to recompile Gosora in order to link the plugin code with Gosora's code. For plugins not written in Go (e.g. JavaScript), they will automatically show up in your Control Panel ready to be installed, although we currently don't support these types of plugins at this time.
   111  
   112  There are also some experimental plugins in the `/experimental/` folder like plugin_sendmail which you may want to make use of, although there aren't any particular guarantees about whether they will continue to function or not.
   113  
   114  We're currently in the process of moving plugins from the `/` to the `/extend/` folder, if there is a piece of functionality that you would like to tap into, but which you cannot from that package, then feel free to poke me, otherwise you may need to drop it in `/` and name the package accordingly.
   115  
   116  
   117  # Images
   118  ![Shadow Theme](https://github.com/Azareal/Gosora/blob/master/images/shadow.png)
   119  
   120  ![Shadow Quick Topic](https://github.com/Azareal/Gosora/blob/master/images/quick-topics.png)
   121  
   122  ![Tempra Simple Theme](https://github.com/Azareal/Gosora/blob/master/images/tempra-simple.png)
   123  
   124  ![Tempra Simple Topic List](https://github.com/Azareal/Gosora/blob/master/images/topic-list.png)
   125  
   126  ![Tempra Simple Mobile](https://github.com/Azareal/Gosora/blob/master/images/tempra-simple-mobile-375px.png)
   127  
   128  ![Cosora Prototype WIP](https://github.com/Azareal/Gosora/blob/master/images/cosora-wip.png)
   129  
   130  More images in the /images/ folder. Beware though, some of them are *really* outdated. Also, keep in mind that a new theme is in the works.
   131  
   132  # Dependencies 
   133  
   134  These are the libraries and pieces of software which Gosora relies on to function, an "ingredients" list so to speak.
   135  
   136  A few of these like Rez aren't currently in use, but are things we think we'll need in the very near future and want to have those things ready, so that we can quickly slot them in.
   137  
   138  * Go 1.11+
   139  
   140  * MariaDB (or any other MySQL compatible database engine). We'll allow other database engines in the future.
   141  
   142  * github.com/go-sql-driver/mysql For interfacing with MariaDB.
   143  
   144  * golang.org/x/crypto/bcrypt For hashing passwords.
   145  * golang.org/x/crypto/argon2 For hashing passwords.
   146  
   147  * github.com/Azareal/gopsutil For pulling information on CPU and memory usage. I've temporarily forked this, as we were having stability issues with the latest build.
   148  
   149    * github.com/StackExchange/wmi Dependency for gopsutil on Windows.
   150  
   151    * golang.org/x/sys/windows Also a dependency for gopsutil on Windows. This isn't needed at the moment, as I've rolled things back to an older more stable build.
   152  
   153  * github.com/gorilla/websocket Needed for Gosora's Optional WebSockets Module.
   154  
   155  * github.com/robertkrimen/otto Needed for the upcoming JS plugin type.
   156  
   157    * gopkg.in/sourcemap.v1 Dependency for Otto.
   158  
   159  * github.com/lib/pq For interfacing with PostgreSQL. You will be able to pick this instead of MariaDB soon.
   160  
   161  * ithub.com/denisenkom/go-mssqldb For interfacing with MSSQL. You will be able to pick this instead of MSSQL soon.
   162  
   163  * github.com/bamiaux/rez An image resizer (e.g. for spitting out thumbnails)
   164  
   165    * github.com/esimov/caire The other image resizer, slower but may be useful for covering cases Rez does not. A third faster one we might point to at some point is probably Discord's Lilliput, however it requires a C Compiler and we don't want to add that as a dependency at this time.
   166  
   167  * github.com/fsnotify/fsnotify A library for watching events on the file system.
   168  
   169  * github.com/pkg/errors Some helpers to make it easier for us to track down bugs.
   170  
   171  * More items to come here, our dependencies are going through a lot of changes, and I'll be documenting those soon ;)
   172  
   173  # Bundled Plugins
   174  
   175  There are several plugins which are bundled with the software by default. These cover various common tasks which aren't common enough to clutter the core with or which have competing implementation methods (E.g. plugin_markdown vs plugin_bbcode for post mark-up).
   176  
   177  * Hey There / Skeleton / Hey There (JS Version) - Example plugins for helping you learn how to develop plugins.
   178  
   179  * BBCode - A plugin in early development for converting BBCode Tags into HTML.
   180  
   181  * Markdown - An extremely simple plugin for converting Markdown into HTML.
   182  
   183  * Social Groups - An extremely unstable WIP plugin which lets users create their own little discussion areas which they can administrate / moderate on their own.
   184  
   185  # Developers
   186  
   187  There are a few things you'll need to know before running the more developer oriented features like the tests or the benchmarks.
   188  
   189  The benchmarks are currently being rewritten as they're currently extremely serial which can lead to severe slow-downs when run on a home computer due to the benchmarks being run on the one core everything else is being run on (Browser, OS, etc.) and the tests not taking parallelism into account.