-
Notifications
You must be signed in to change notification settings - Fork 7
Full steps to run PutsBox in development
We've been using PutsBox for E2E email testing integration in our automation framework 'Steve' for over a year, it's great!
PutsBox allows you to instantly create a brand-new temporary-but-real email inbox, and then use a UI to check that those emails arrive, (you can view them as HTML too, if you need to check visual stuff) you can even do some analysis on the attachments. It solves a lot of the problems we come across, and problems we see mentioned in the testing community. And it's free and it's swanky.
PutsBox really is just a clever extension for the SendGrid inbound email parse web-hook. What it does - is when SendGrid receives an email to the Domain specified - it then POSTs that email to PutsBox, where there is a Rails app back-end and lush React front-end that do the magic of processing email parameters and content and splitting them up into [what PutsBox calls] 'Buckets' - for each email address.
Give it a go - visit PutsBox, create a new bucket and send that address an email. A few seconds later the magic occurs.
After a year of putting boxes - many thousands of them - we came across a few times where Heroku was down, or PutsBox itself was borked. This doesn't need to be an issue, as you can run it yourself.
This should also get over some issues with your data security, and you can then fork it to be containerised, or to adjust settings (like the expiry time of your bucket, or user). In short, you could create a world where you make an individual bucket that lasts forever, every time you wanted to send an email... Programmatically-wise this means you would possibly never have issues with security, or duplication, or anything ever again, right? That's what we thought. You can create buckets with any email you like (our integration does this already), and destroy them immediately after reading, like James Bond, or keep them forever, like a diamond.
Turned out it was a little bit of a PITA to setup, but here's how:
You'll want to use a machine that faces the internet, or else it'll be a bit harder and we're not covering that for security reasons. You need to create a free SendGrid account. You should own a domain that you can administrate.
Install: [at time of writing]
- git
-
ruby 2.5.5,rvm,rvm use 2.5.5,rails,bundler(gem install bundler) https://rvm.io/rvm/install = you can install rails with this or independently, up to you. - mongodb
fedora / centos etc:
sudo yum install mongodb-org
sudo systemctl start mongod
OSX:
brew install mongo
mongod
writer note: you might need to run mongod in a separate window with this osx tutorial, or as a background process, we didn't go that far as to find out. we also had some issues mongoing, so needed to create some folders and adjust their permissions [unix-based OS agnostic I hope]:
sudo mkdir -p /data/db
sudo chmod 0755 /data/db
sudo chown -R mongod:mongod /data/db
sudo chown -R `id -u` /data/db
sudo chmod -R go+w /data/db
- rails
- devise
fedora/centos etc
gem install devise
OR
add gem 'devise'
to your Gemfile (may already get installed by bundler)
OSX:
brew install devise
- PutsBox
git git clone [email protected]:phstc/putsbox.git
cd putsbox
bundle install
rails server
- stuff
You may have some issues with keys here, here's a few handy shell commands I used, along with google and the PutsBox issue tracker. If you're on a completely new env you'll need to have ssh keys etc too. use
bundle exec rake secret
to make a key and use it to edit
config/initializers/secret_token.rb
then add the necessary stuff to config/secrets.yml
(you can copy this etc, but change the keys!)
bundle exec rspec
Does this work? I hope so, if not, google is your friend.
It works?
bundle exec rails server
Now try and access the app through port 3000 on the machines localhost, or wherever you might have put it. Do you see a PutsBox UI? Hope so!
This is where it maybe gets a little more complicated, depends on how easy you find the next bit. You may want to go to bed first. Or drink stimulating drinks.
Set yourself up a SendGrid trial. Or use your existing account.
It should be free for what we're using it for.
Buy or use an existing domain. In your domain provider, change the nameserver settings to reflect those of your hosting providers. (writer used 123-reg's tutorial and then we used DigitalOcean's tutorial and we used the SendGrid tutorial (in fact you have to run through a few hoops ay SendGrid to even do this, validating your domain ownership. Then we used some more DigitalOcean tutorials. Your milage will vary based on your domain provider and hosting, and the order that you do these things in may vary too.
You need to tell the SendGrid parse setting to POST to the url that your PutsBox app is running at + /record (I.E. https://myputsbox.me.com/record)
By the end of it you should be able to send an email to {blah}@{blah.yourdomain}.{blah}. and SendGrid will POST to your PutsBox app. If you're running the app in a terminal you should see this in the traffic. If you do, Good work!
In
/app/controllers/buckets_controller.rb
change the line
email_params['email'] = envelope['to'].select { |to| to.downcase.end_with? '@putsbox.com' }.first
to your email domain. Otherwise PutsBox will get a nil error.
Replace the same domain into
config/environments/production.rb
app/views/buckets/_form.html.erb
app/helpers/application_helper.rb
Or else your PutsBox UI will default to referring to the old putsbox.com url. The writer had another error trying to preview an email:
This site can’t be reached
preview.{blah}’s server IP address could not be found.
DNS_PROBE_FINISHED_NXDOMAIN
This was because I had used my domain provider's DNS settings, which led to me getting confused and using my hosting provider's DNS settings directly instead, which worked - and now the subdomain preview worked for the writer's PutsBox application. ¯\_(ツ)_/¯
It sounds like a lot, but you can have it done in an hour. I can't guarantee that your MX records etc will propagate instantly, but they might. Good luck.
Now when I send an email to my new subdomain, it appears in my PutsBox buckets, and I am in full control, and not costing the PutsBox devs any Heroku monies, and we have vanity test email urls, sorted! 👍