. .
.___ ____ _/_ ___ _/_ , . ____
/ \ ( | / ` | | | (
| ' `--. | | | | | | `--.
/ \___.' \__/ `.__/| \__/ / `._/| \___.'
rstat.us is a microblogging site built on top of the ostatus protocol.
The differences between rstat.us and other microblogging networks are simplicity and openness.
Simplicity is a core 'feature' of rstat.us. We pride ourselves on saying 'no' to lots of features. Our interface is clean, and easy to understand. We give you just enough features to be interesting, but not enough to be complicated and confusing.
Openness means the programming code that makes up rstat.us is available for anyone to download, free of charge. Programmers can use that code to run their own websites just like rstat.us, and you can subscribe to your friends on any site that supports the OStatus protocol, like identi.ca. This also means that you can own your data; we'll never stop you from having full access to everything you've put into rstat.us.
Deployment
For heroku (free, $0):
Create an account on heroku.com. Then, either use this button:
or follow the manual steps here:
Install their toolchain: https://toolbelt.heroku.com
git clone https://github.com/hotsh/rstat.us
heroku login
heroku apps:create # Creates with a random name
heroku addons:add mongohq # Adds free mongo db (512 MB)
heroku addons:add sendgrid # Adds free email
heroku config:set SECRET_TOKEN=`rake secret`
To use your own domain (optional), register your domain from a domain service (small cost). Create a CNAME to point to your heroku app: http://random-name.herokuapp.com where random-name is the name it chose for you.
heroku domains:add mydomain.tld # Replace mydomain.tld with your registered name
You may have to wait a little while for your dns to resolve.
To hook it up to your twitter account, go to http://dev.twitter.com and add an application.
Use for callback url:
http://mydomain.tld/auth/twitter
or, if you do not have your own domain:
http://random-name.herokuapp.com/auth/twitter
And then "view API keys" and give them to heroku:
heroku config:set CONSUMER_KEY=key # Fill in 'key'
heroku config:set CONSUMER_SECRET=secret # Fill in 'secret'
Eventually:
git push heroku master
Bring up the node in your browser and create a user. Set up your system settings during signup. You may turn off new accounts during original signup or on the admin page at "/admin"
Edit your profile and attach your twitter account if you want.
Quick facts and links
- The stack: ruby (1.9.3 OR 2.0.0 OR 2.1.3)/rails 3.2/mongodb
- The code
- The documentation (We could use lots of improvement here!)
- The Issues list
- Tests are written using minitest and capybara
- Documentation is generated using docco (rocco)
How to get help
- If you think you've found a bug, please file a new issue and include:
- What happened
- What you expected to happen
- Steps to reproduce what happened
- You can send questions, problems, or suggestions to the mailing list
- Chat with us on IRC in #rstatus on freenode
Helping out with rstat.us
If you'd like to contribute, we'd love to have you! Your first order of business is setting up a development environment and making sure all the tests pass on your system. Rstat.us is a Ruby on Rails 3.2 application, so it's assumed you already have Ruby (1.9.3, 2.0.0 or 2.1.3 preferred, 1.8.7/1.9.2 compatibility is not guaranteed), rubygems (comes with Ruby), and bundler on your machine. If not, each of those links has instructions, and we're willing to help via one of the contact methods above if you have issues.
Automated Setup
There is an automated script to get your dev environment set up on Mac OS X. From the app root directory, run ./script/setup_mac and enjoy the ride. If everything installs correctly and no errors are reported that you need to fix, you'll see the site loaded in your favorite browser.
- mongodb
- Homebrew preferred for installing mongodb
- MacPorts should also work
- Take a look at the mongodb-prefpane
If there are any errors reported, fix what you can and let us know what you can't.
Manual Setup
If you have any problems with the following rstat.us specific steps, it is a bug. For example, this is an issue with running a development environment on windows that we need to fix. Please report any issues you have.
Getting a local version running
First off: you will need MongoDB (www.mongodb.org). They have a quickstart guide for getting it installed and running.
Fork the project in github so that you have your own version.
Then do:
$ git clone https://github.com/$MY_GITHUB_USERNAME/rstat.us.git
$ cd rstat.us
Then update your gemset:
$ gem install bundler && bundle install
The config.yml file will be automatically copied/generated for you when you start the server and it does not exist. In dev mode the SECRET_TOKEN will be generated for you and your config.yml file updated. When you run tests a new random SECRET_TOKEN will be generated each time. You can always copy config/config.yml.sample to config/config.yml and edit it on your own beforehand.
- encoding is UTF-8 by default
- Notes about config settings are in the example file (config/config.yml.example)
And start the server:
$ rails server
Bam! Visit http://localhost:3000/ in your browser, and you'll be good.
Local Twitter configuration
Rstat.us allows you to sign in using a Twitter account or link a Twitter account to your Rstat.us account. If you'd like to enable that functionality in your dev environment, you'll need to obtain a consumer key and consumer secret from Twitter. Here are the steps to do that:
- Go to https://dev.twitter.com
- Sign in using a valid Twitter account
- Hover over your username in the top right and select "My applications"
- Select "Create a new application"
- Fill in all the required fields (you can use made up information if you'd like) and be sure to add a "Callback URL" - e.g. http://rstat.us
- Go to the settings tab and select "Read and Write" for the application's access type
- If you haven't already, create a personal
config/config.ymlby copyingconfig/config.yml.sample - Copy the consumer key and consumer secret (found on the details tab)
and put them in
config/config.ymlin the development section - Restart your rails server
Now you should be able to sign in to your development version with Twitter!
Running the tests
To run the tests you may want to make use of bundle exec so you don't get
mixed up with different versions of gems that might or might not work with
the current rstat.us branch.
Run all the tests except for the optional enhancements. This is fine for smaller features that are not likely to affect enhancements:
$ bundle exec rake test
Run all the tests including those for all the optional enhancements. This requires that you have all the enhancements configured locally (see the section on Configuring optional enhancements below). This is recommended if you're working on a larger feature that touches many parts of the application and is required if you're working on an enhancement. This is the command that Travis.ci runs.
$ bundle exec rake test:all
You can run convenient subsets of the tests during development; run bundle exec rake -T to see all the options. You can also run one test file (for
example, test/models/author_test.rb) by specifying the filepath in the TEST
environment variable:
$ bundle exec rake test TEST=test/models/author_test.rb
Picking something to work on
Once you've got a development environment set up with the current tests all passing, you're ready to start working on the code!
Please see the Issues; anything without an assignee is up for grabs! Fairly well-defined and small issues are tagged with Pick me!!!!!!; these would be ideal if you want to help out but aren't sure where to start. Don't hesitate to ask for help or clarification either on an issue itself or through one of the contact methods listed above.
Development Roadmap
In the second half of 2012, we plan to focus on:
We'd love to get rstat.us working with desktop and mobile clients, either through a twitter-compatible API in a client that allows you to change the endpoint URL or working with an app developer to make an rstat.us-specific app. If you work on or would like to work on a client, please let us know! We'd love to get feedback from you.
Contribution steps
We follow GitHub flow, as a workflow. Basically:
- Create a feature branch in your fork
- Make your change, including tests and documentation as appropriate
- Please run all the tests before submitting a pull request!
- Submit a pull request from your branch
- Someone with commit access will let you know they are looking at it as soon as they are able. They will review the code and let Travis.ci run the tests before merging. This applies even if you also have commit access.
Becoming a committer
Following rubinius' lead, once you have one pull request accepted into rstat.us, we will add you to a team that has push+pull access. Basically you will get a big green merge button on other people's pull requests, and you will be able to commit those pull requests to the hotsh/rstat.us master branch.
This also means that you could push your commits directly to hotsh/rstat.us without going through a pull request. We ask that you not do this, however, so that any code on master has been seen by 2 sets of eyes (tests don't always catch everything!) This does not apply to branches other than master; if there is long-term collaboration happening, create a feature branch and feel free to push directly to that (but have commits reviewed before merging that branch into master).
We reserve the right to take away this permission, but in general we trust you to give it to you. ❤️ ❤️
Source code documentation
We have documentation that explains our source code using rocco. You can view it here.
Configuring optional enhancements
When running your own node, you will be able to make choices about what features your node should offer. These will typically require additional configuration or setup. The currently available enhancements are:
ElasticSearch
The Rstat.us code is able to use ElasticSearch to improve the quality of the search of statuses. This is optional for development, test, and production. The code will fall back to a simpler regular expression search should you choose not to enable the ElasticSearch support.
Local development and test:
If you are using OSX and homebrew, you can install ElasticSearch using:
$ brew install elasticsearch
Otherwise, you can download and install the latest release from the ElasticSearch website.
If you are running ElasticSearch on the default port of 9200, specify this as
the ELASTICSEARCH_INDEX_URL in your config/config.yml file in either or both
the development and test environments:
ELASTICSEARCH_INDEX_URL: http://localhost:9200/
Production on heroku:
The code is set up to work with the Bonsai Heroku addon. Check that article for the most up-to-date instructions. As of this writing you should simply be able to do:
$ heroku addons:add bonsai:test
This will add a heroku config value for BONSAI_INDEX_URL that will automatically be picked up by the code for all new statuses entered.
To index existing updates, run:
$ heroku run rake environment tire:import CLASS='Update'
Production on other hosts:
If you are hosting your node somewhere other than heroku and have installed ElasticSearch on your own, set the environment variable ELASTICSEARCH_INDEX_URL to the domain where your ElasticSearch service is.