writefreely/README.md

135 lines
5.1 KiB
Markdown
Raw Normal View History

 
<p align="center">
2018-11-12 00:37:13 +01:00
<a href="https://writefreely.org"><img src="https://writefreely.org/img/writefreely.svg" width="350px" alt="Write Freely" /></a>
</p>
<hr />
<p align="center">
2018-10-17 04:51:42 +02:00
<a href="https://github.com/writeas/writefreely/releases/">
<img src="https://img.shields.io/github/release/writeas/writefreely.svg" alt="Latest release" />
</a>
2018-11-08 07:55:50 +01:00
<a href="https://goreportcard.com/report/github.com/writeas/writefreely">
<img src="https://goreportcard.com/badge/github.com/writeas/writefreely" alt="Go Report Card" />
</a>
2018-10-17 04:51:42 +02:00
<a href="https://travis-ci.org/writeas/writefreely">
<img src="https://travis-ci.org/writeas/writefreely.svg" alt="Build status" />
</a>
2018-11-12 00:37:13 +01:00
<a href="http://webchat.freenode.net/?channels=writefreely">
2018-11-12 19:40:38 +01:00
<img alt="#writefreely on freenode" src="https://img.shields.io/badge/freenode-%23writefreely-blue.svg" />
2018-11-12 00:37:13 +01:00
</a>
</p>
2018-10-17 04:39:46 +02:00
&nbsp;
2018-01-25 01:52:16 +01:00
2018-10-17 04:39:46 +02:00
WriteFreely is a beautifully pared-down blogging platform that's simple on the surface, yet powerful underneath.
2018-01-25 01:52:16 +01:00
2018-11-21 17:54:01 +01:00
It's designed to be flexible and share your writing widely, so it's built around plain text and can publish to the _fediverse_ via ActivityPub. It's easy to install and light enough to run on a Raspberry Pi.
2018-01-25 01:52:16 +01:00
2018-11-10 22:19:05 +01:00
**[Start a blog on our instance](https://write.as/new/blog/federated)**
[Try the editor](https://write.as/new)
[Find another instance](https://writefreely.org/instances)
2018-11-08 07:55:50 +01:00
2018-01-25 01:52:16 +01:00
## Features
* Start a blog for yourself, or host a community of writers
* Form larger federated networks, and interact over modern protocols like ActivityPub
2018-11-08 07:55:50 +01:00
* Write on a dead-simple, distraction-free and super fast editor
* Publish drafts and let others proofread them by sharing a private link
2018-10-17 04:39:46 +02:00
* Build more advanced apps and extensions with the [well-documented API](https://developers.write.as/docs/api/)
2018-01-25 01:52:16 +01:00
2018-11-08 07:34:23 +01:00
## Quick start
2018-11-10 22:19:05 +01:00
> **Note** this is currently alpha software. We're quickly moving out of this v0.x stage, but while we're in it, there are no guarantees that this is ready for production use.
2018-11-08 07:34:23 +01:00
First, download the [latest release](https://github.com/writeas/writefreely/releases/latest) for your OS. It includes everything you need to start your blog.
Now extract the files from the archive, change into the directory, and do the following steps:
```bash
# 1) Log into MySQL and run:
# CREATE DATABASE writefreely;
#
# 2) Configure your blog
2018-11-08 07:34:23 +01:00
./writefreely --config
# 3) Import the schema with:
./writefreely --init-db
# 4) Generate data encryption keys
./writefreely --gen-keys
2018-11-08 07:34:23 +01:00
# 5) Run
./writefreely
# 6) Check out your site at the URL you specified in the setup process
# 7) There is no Step 7, you're done!
```
2018-11-10 22:33:56 +01:00
For running in production, [see our guide](https://writefreely.org/start#production).
2018-11-08 07:34:23 +01:00
## Development
Ready to hack on your site? Here's a quick overview.
### Prerequisites
* [Go 1.10+](https://golang.org/dl/)
* [Node.js](https://nodejs.org/en/download/)
### Setting up
```bash
go get github.com/writeas/writefreely/cmd/writefreely
```
Configure your site, create your database, and import the schema [as shown above](#quick-start). Then generate the remaining files you'll need:
2018-11-08 07:34:23 +01:00
```bash
make install # Generates encryption keys; installs LESS compiler
make ui # Generates CSS (run this whenever you update your styles)
make run # Runs the application
2018-11-08 07:34:23 +01:00
```
## Docker
### Using Docker for Development
If you'd like to use Docker as a base for working on a site's styles and such,
you can run the following from a Bash shell.
*Note: This process is intended only for working on site styling. If you'd
like to run Write Freely in production as a Docker service, it'll require a
little more work.*
The `docker-setup.sh` script will present you with a few questions to set up
your dev instance. You can hit enter for most of them, except for "Admin username"
and "Admin password." You'll probably have to wait a few seconds after running
`docker-compose up -d` for the Docker services to come up before running the
bash script.
```
docker-compose up -d
./docker-setup.sh
```
Now you should be able to navigate to http://localhost:8080 and start working!
When you're completely done working, you can run `docker-compose down` to destroy
your virtual environment, including your database data. Otherwise, `docker-compose stop`
will shut down your environment without destroying your data.
### Using Docker for Production
Write Freely doesn't yet provide an official Docker pathway to production. We're
working on it, though!
2018-11-21 17:54:01 +01:00
## Contributing
We gladly welcome contributions to WriteFreely, whether in the form of [code](https://github.com/writeas/writefreely/blob/master/CONTRIBUTING.md#contributing-to-writefreely), [bug reports](https://github.com/writeas/writefreely/issues/new?template=bug_report.md), [feature requests](https://discuss.write.as/c/feedback/feature-requests), [translations](https://poeditor.com/join/project/TIZ6HFRFdE), or documentation improvements.
Before contributing anything, please read our [Contributing Guide](https://github.com/writeas/writefreely/blob/master/CONTRIBUTING.md#contributing-to-writefreely). It describes the correct channels for submitting contributions and any potential requirements.
2018-01-25 01:52:16 +01:00
## License
2018-10-29 15:06:45 +01:00
Licensed under the AGPL.