gosora/README.md

251 lines
13 KiB
Markdown
Raw Normal View History

# Gosora [![Azareal's Discord Chat](https://img.shields.io/badge/style-Invite-7289DA.svg?style=flat&label=Discord)](https://discord.gg/eyYvtTf)
2016-12-02 07:32:57 +00:00
A super fast forum software written in Go. You can talk to us on our Discord chat!
2016-12-02 07:32:57 +00:00
The initial code-base was forked from one of my side projects, but has now gone far beyond that. We're still fairly early in development, so the code-base might change at an incredible rate. We plan to stop making as many breaking changes once we release the first alpha.
If you like this software, please give it a star and give us some feedback :)
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 change many things before the alpha!
2016-12-02 07:32:57 +00:00
# Features
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.
Custom Pages. Under development. The Control Panel portion is incomplete, but you can create them by hand today. They're basically html/templates templates in the /pages/ folder.
Emojis. Allow your users to express themselves without resorting to serving tons upon tons of image files.
2016-12-08 14:24:19 +00:00
In-memory static file, forum and group caches. We have a slightly more dynamic cache for users and topics.
2016-12-08 14:24:19 +00:00
A profile system, including profile comments and moderation tools for the profile owner.
2016-12-08 14:24:19 +00:00
A template engine which compiles templates down to machine code. Over thirty times faster than html/templates, although it does remove some of the hand holding to achieve this. Compatible with templates written for html/templates, you don't need to learn any new templating language.
A plugin system. More on this to come.
A responsive design. Looks great on mobile phones, tablets, laptops, desktops and more!
Other modern features like alerts, likes, advanced dashboard with live stats (CPU, RAM, online user count, and so on), etc.
2016-12-02 07:32:57 +00:00
# Dependencies
Go 1.10 - 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
2016-12-02 07:32:57 +00:00
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.
2017-01-10 07:49:48 +00:00
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.
Instructions on how to set MariaDB up on Linux: https://downloads.mariadb.org/mariadb/repositories/
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.
2016-12-02 07:32:57 +00:00
It's entirely possible that your host might already have MySQL, so you might be able to skip this step, particularly if it's a managed VPS or a shared host (contrary to popular belief, it is possible, although the ecosystem in this regard is extremely immature). Or they might have a quicker and easier method of setting up MySQL.
2016-12-02 07:32:57 +00:00
Fixed a bug where it would use the wrong templates for Tempra Simple, Tempra Cursive, and Shadow Likes are now done over AJAX. Posts you have liked are now visually differentiated from those which you have not. Added support for OR to the where parser. || and && now get translated to OR and AND in the where parser. Added support for ( and ) in the where parser. Added an adapter and builder method for getting the database version. Multiple wheres can now be chained with the micro and accumulator builders. Added the In method to the accumulator select builder. Added the GetConn method to the builder. /uploads/ files should now get cached properly. Added more tooltips for topic titles and usernames. Fixed a bug in the runners where old stale templates would be served. Fixed a bug where liking topics didn't work. Began moving the database initialisation logic out of {adapter}.go and into querygen. Tweaked the alert direction to show the newest alerts rather than the oldest. Tweaked the WS JS to have it handle messages more efficiently. Partially fixed an issue where inline edited posts would lack newlines until the page is refreshed. Used arrow functions in a few places in global.js to save a few characters. Schema: Added the liked, oldestItemLikedCreatedAt and lastLiked columns to the users table. Added the createdAt column to the likes table. MySQL Update Queries: ALTER TABLE `users` ADD COLUMN `liked` INT NOT NULL DEFAULT '0' AFTER `topics`; ALTER TABLE `users` ADD COLUMN `oldestItemLikedCreatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP AFTER `liked`; ALTER TABLE `users` ADD COLUMN `lastLiked` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP AFTER `oldestItemLikedCreatedAt`; ALTER TABLE `likes` ADD COLUMN `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP AFTER `sentBy`; delete from `likes`; delete from `activity_stream` where `event` = 'like'; delete from `activity_stream_matches` where `asid` not in(select `asid` from `activity_stream`); update `topics` set `likeCount` = 0; update `replies` set `likeCount` = 0;
2018-03-31 05:25:27 +00:00
# Downloading
At some point, we'll have releases which you can download, but right now, you'll have to use the `git clone` command as mentioned down in the advanced setup section to download a copy of Gosora.
On Windows, you might also want to try the [GosoraBootstrapper](https://github.com/Azareal/GosoraBootstrapper), if you can't find the command prompt. It's just a matter of double-clicking on the bat file there and it'll download the rest of the files for you.
Fixed a bug where it would use the wrong templates for Tempra Simple, Tempra Cursive, and Shadow Likes are now done over AJAX. Posts you have liked are now visually differentiated from those which you have not. Added support for OR to the where parser. || and && now get translated to OR and AND in the where parser. Added support for ( and ) in the where parser. Added an adapter and builder method for getting the database version. Multiple wheres can now be chained with the micro and accumulator builders. Added the In method to the accumulator select builder. Added the GetConn method to the builder. /uploads/ files should now get cached properly. Added more tooltips for topic titles and usernames. Fixed a bug in the runners where old stale templates would be served. Fixed a bug where liking topics didn't work. Began moving the database initialisation logic out of {adapter}.go and into querygen. Tweaked the alert direction to show the newest alerts rather than the oldest. Tweaked the WS JS to have it handle messages more efficiently. Partially fixed an issue where inline edited posts would lack newlines until the page is refreshed. Used arrow functions in a few places in global.js to save a few characters. Schema: Added the liked, oldestItemLikedCreatedAt and lastLiked columns to the users table. Added the createdAt column to the likes table. MySQL Update Queries: ALTER TABLE `users` ADD COLUMN `liked` INT NOT NULL DEFAULT '0' AFTER `topics`; ALTER TABLE `users` ADD COLUMN `oldestItemLikedCreatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP AFTER `liked`; ALTER TABLE `users` ADD COLUMN `lastLiked` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP AFTER `oldestItemLikedCreatedAt`; ALTER TABLE `likes` ADD COLUMN `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP AFTER `sentBy`; delete from `likes`; delete from `activity_stream` where `event` = 'like'; delete from `activity_stream_matches` where `asid` not in(select `asid` from `activity_stream`); update `topics` set `likeCount` = 0; update `replies` set `likeCount` = 0;
2018-03-31 05:25:27 +00:00
# Installation Instructions
2016-12-02 07:32:57 +00:00
*Linux*
2016-12-08 14:24:19 +00:00
cd to the directory / folder the code is in. In other words, type cd followed by the location of the code and it should jump there.
2016-12-02 07:32:57 +00:00
Run ./install-linux
2016-12-02 07:32:57 +00:00
Follow the instructions shown on the screen.
*Windows*
2016-12-02 07:32:57 +00:00
Run install.bat, e.g. double-click on it. You will also have to start-up MySQL, which if you're using Wnmp or friends is just a matter of opening that program and starting the MySQL process via it.
Follow the instructions shown on the screen.
# Run the program
*Linux*
In the same directory you installed it, you simply have to type: ./run-linux
*Windows*
Run run.bat, e.g. double-clicking on it.
*Updating Dependencies*
You can update the dependencies which Gosora relies on by running update-deps.bat on Windows or ./update-deps-linux on Linux. These dependencies do not include Go or MySQL, those have to be updated separately.
We're also looking into ways to distribute ready made executables for Windows. While this is not a complicated endeavour, the configuration settings currently get built with the rest of the program for speed, and we will likely have to change this.
With the introduction of the new settings system, we will begin moving some of the less critical settings out of the configuration file, and will likely have a config.xml or config.ini in the future to store the critical settings in.
You'll need to restart the server every-time you change a template, e.g. with `run.bat` or `./run-linux`
2016-12-24 01:07:32 +00:00
Several important features for saving memory in the templates system may have to be implemented before the new compiled template system is rolled out to every route. These features are coming fairly soon, but not before the higher priority items.
2016-12-24 01:07:32 +00:00
2016-12-02 07:32:57 +00:00
# Advanced Installation
This section explains how to set things up without running the batch or shell files. For Windows, you will likely have to open up cmd.exe (the app called Command Prompt in Win10) to run these commands inside or something similar, while with Linux you would likely use the Terminal or console.
Linux is similar, however you might need to use cd and mv a bit more like in the shell files due to the differences in go build across platforms. Additionally, Linux doesn't require `StackExchange/wmi` or `/x/sys/windows`
You also need to substitute the `gosora.exe` bits for `./Gosora` on Linux. For more info, you might want to take a gander inside the `./run-linux` and `./install-linux` shell files to see how they're implemented.
If you want to skip typing all the `go get`s, you can run `./update-deps.bat` (Windows) or `./update-deps-linux` to do that for you.
```bash
git clone https://github.com/Azareal/Gosora
go get -u github.com/go-sql-driver/mysql
go get -u golang.org/x/crypto/bcrypt
go get -u github.com/StackExchange/wmi
go get -u github.com/Azareal/gopsutil
go get -u github.com/gorilla/websocket
2017-09-29 04:42:35 +00:00
go get -u gopkg.in/sourcemap.v1
go get -u github.com/robertkrimen/otto
go get -u github.com/lib/pq
go get -u github.com/denisenkom/go-mssqldb
go get -u github.com/fsnotify/fsnotify
go get -u github.com/gopherjs/gopherjs/...
go generate
go build ./router_gen
router_gen.exe
go build ./query_gen
query_gen.exe
go build -o gosora.exe
go build ./install
install.exe
gosora.exe -build-templates
2017-06-07 10:12:19 +00:00
gosora.exe
```
I'm looking into minimising the number of go gets for the advanced build and to maybe remove the platform and database engine specific dependencies if possible for those who don't need them.
# Updating
The update system is currently under development, however if you have Git installed, then you can run `dev-update.bat` or `dev-update-linux` to update your instance to the latest commit and to update the associated database schema, etc.
In addition to this, you can update the dependencies without updating Gosora by running `update-deps.bat` or `./update-deps-linux` (.bat is for Windows, the other for Linux as the names would suggest).
If you want to manually patch Gosora rather than relying on the above scripts to do it, you'll first have to create a copy of `./schema/schema.json` named `./schema/lastSchema.json`, and then, you'll overwrite the files with the new ones.
After that, you'll need to run `go build ./patcher` on Windows or the following code block on Linux:
```
cd ./patcher
go build -o Patcher
mv ./Patcher ..
```
Once you've done that, you just need to run `patcher.exe` (Windows) or `./Patcher` to apply the latest patches to the database, etc.
# How do I install plugins?
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 drag them from your /extend/ directory and into the / directory (the root directory of your Gosora installation, where the executable and most of the main Go files are).
You will then need to recompile Gosora in order to link the plugin code with Gosora's code. For plugins not written in Gosora (e.g. JavaScript), you do not need to move them from the /extend/ directory, they will automatically show up in your Control Panel ready to be installed.
Experimental plugins aka the ones in the /experimental/ folder (e.g. plugin_sendmail) are similar but different. You will have to move native plugins (ones written in Go) to the root directory of your installation and will have to move experimental plugins written in other languages into the /extend/ directory.
We're looking for ways to clean-up the plugin system so that all of them (except the experimental ones) are housed in /extend/, however we've encountered some problems with Go's packaging system. We plan to fix this issue in the future.
# Images
![Shadow Theme](https://github.com/Azareal/Gosora/blob/master/images/shadow.png)
![Shadow Quick Topic](https://github.com/Azareal/Gosora/blob/master/images/quick-topics.png)
2017-01-07 06:46:08 +00:00
![Tempra Simple Theme](https://github.com/Azareal/Gosora/blob/master/images/tempra-simple.png)
![Tempra Simple Topic List](https://github.com/Azareal/Gosora/blob/master/images/topic-list.png)
![Tempra Simple Mobile](https://github.com/Azareal/Gosora/blob/master/images/tempra-simple-mobile-375px.png)
Happy 100th commit! For the 100th commit, I've revamped a good portion of the user interface, and we don't plan on stopping! There's more to come! Each theme has more of a distinct feel in the control panel now. I moved a large portion of the inline CSS into global.css, tweaked some core code which didn't line up, and added CSS text insertions to make things more flexible. Revamped the alerts interface. We have more changes coming up! Added screenshots for Tempra Cursive and Tempra Conflux Mobile to the README. Added a .htaccess file, just in case someone plops Gosora in Apache's /www/ folder to stop the contents of config.go from becoming publically visible. Never put Gosora in your /www/ folder, Gosora is a standalone program which does NOT use Apache or any other webserver. Fixed a bug in the inline forum editor. Added a hand-written Markdown parser which is much faster than the previous Regex based one. This is still a work in progress. Added support for strikethrough and underline elements to the Markdown parser. Fixed the missing semicolons in global.js Revamped the form CSS. Author bits on the theme manager now link to the author's website. Improved the profiles a little. The code in the stylesheets now have a more consistent style. Fixed a bug in the Cosmo theme relating to the fact that Gosora doesn't have sidebars yet. There are many more changes which aren't listed here. If weirdness regarding lines or spacing occurs, I'm experimenting with a new text editor. I hope to have this fixed by the next commit.
2017-05-29 14:52:37 +00:00
![Tempra Cursive Theme](https://github.com/Azareal/Gosora/blob/master/images/tempra-cursive.png)
2017-01-07 06:46:08 +00:00
![Tempra Conflux Theme](https://github.com/Azareal/Gosora/blob/master/images/tempra-conflux.png)
![Tempra Conflux Mobile](https://github.com/Azareal/Gosora/blob/master/images/tempra-conflux-mobile-320px.png)
![Cosora Prototype WIP](https://github.com/Azareal/Gosora/blob/master/images/cosora-wip.png)
More images in the /images/ folder. Beware though, some of them are *really* outdated.
# Dependencies (a few of these like Rez aren't currently in use, but we anticipate that we'll need some sort of search engine library in the very immediate future)
* Go 1.10+
* MariaDB (or any other MySQL compatible database engine). We'll allow other database engines in the future.
* github.com/go-sql-driver/mysql For interfacing with MariaDB.
* golang.org/x/crypto/bcrypt For hashing passwords.
* 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.
* github.com/StackExchange/wmi Dependency for gopsutil on Windows.
* 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.
* github.com/gorilla/websocket Needed for Gosora's Optional WebSockets Module.
* github.com/robertkrimen/otto Needed for the upcoming JS plugin type.
* gopkg.in/sourcemap.v1 Dependency for Otto.
* github.com/lib/pq For interfacing with PostgreSQL. You will be able to pick this instead of MariaDB soon.
* ithub.com/denisenkom/go-mssqldb For interfacing with MSSQL. You will be able to pick this instead of MSSQL soon.
* github.com/bamiaux/rez An image resizer (e.g. for spitting out thumbnails)
* github.com/fsnotify/fsnotify A library for watching events on the file system.
# Bundled Plugins
2016-12-24 01:07:32 +00:00
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).
* Hey There / Skeleton / Hey There (JS Version) - Example plugins for helping you learn how to develop plugins.
* BBCode - A plugin in early development for converting BBCode Tags into HTML.
* Markdown - An extremely simple plugin for converting Markdown into HTML.
* Social Groups - A WIP plugin which lets users create their own little discussion areas which they can administrate / moderate on their own.
# Developers
There are a few things you'll need to know before running the more developer oriented features like the tests or the benchmarks.
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.