Deploy to Heroku

You can host your own version of screeenly on Heroku for free.(*) This page will guide you through the steps required to set everything up.

Before we start, a few requirements and notes:

• You will need a Heroku-account.
• Apps deployed to Heroku use an ephermal filesystem. This means, that we need to add a persistent filesystem like AWS S3, if you want to reference a screenshot by a URL (eg. https://screeenly.example.com/screenshots/abc123.jpg).
• If you will use the base64 response value from the screeenly API, you do not need to setup an AWS account and don't need an S3 bucket.
• The whole setup is not done in a single click. You will need to configure some server variables. So plan some time.

Deploy to Heroku

Let's deploy the app to Heroku. After the deployment is done, we will need to set config variables to make the app work.

1. Click on the following link to instruct Heroku to deploy screeenly: Deploy to Heroku
2. Give your app a unique name (eg. screeenly-nextcloud-MYNAME) or let Heroku choose a name for you.
3. Select the region, where the app should be deployed to. (US or Europe)
4. Click on "Deploy app". (The deployment of the app might take a while.)
5. Click on "Manage App" to visit the app dashboard in Heroku.

Set Config Variables

Now that the app has been successfully deployed, we will need to update its config variables to make everything work. Unfortunately this step could not be automated with the "Deploy to Heroku" button. ☹️

1. In the app dashboard click on "Settings" and scroll to the "Config Vars" section. Click on "Reval Config Vars".
2. For each line in the table below, add a new config variable. Read the "description" column carefully to learn where to get the correct value from.

KEY	VALUE	Description
APP_DEBUG	false	Indicates if debugging information should displayed, if an Exception is thrown
APP_ENV	production	The environment the app is in. This should always be "production"
APP_KEY	base64:abc123…	A Laravel encryption key. You can copy and paste a new encryption from this website.
APP_NAME	screeenly	The name of the application
APP_URL	https://unique-name.herokuapp.com	The URL to access your version of screeenly. Should be the unique URL you've got from Heroku.
DB_CONNECTION	pgsql	The database driver used to connect to your database. Leave this as "pqsql" to connect to the Postgres database created during the deployment.
DATABASE_URL	postgres://...	The URI to connect to your Postgres database. This value should have been autofilled by Heroku. If it didn't, here's is how to get that URL:Go to "Resources" and click on "Heroku Postgres". You will be redirected to the database manager. There click on "Settings" and then click on "View Credentials …". The copy and paste the URI value to your config variables.
SESSION_DRIVER	database	Should always be "database" to ensure that you stay logged in.
SCREEENLY_DISABLE_SANDBOX	true	An internal setting to make screeenly work on Heroku.
SCREEENLY_DISK	s3 or public	The filesystem to store generated screenshots on. Set this to "s3" if you use AWS S3. Set it to "public" if you use the base64 encoded value from the API.
AWS_ACCESS_KEY_ID		The AWS access key to access your AWS S3 bucket.
AWS_BUCKET	Example: screeenly-on-heroku	The name of your AWS S3 bucket.
AWS_DEFAULT_REGION	eu-central-1	The AWS region where your S3 bucket is located.
AWS_SECRET_ACCESS_KEY		The AWS secret access key to access your AWS S3 bucket.
AWS_URL	Example: https://screeenly-on-heroku.s3.eu-central-1.amazonaws.com	The URL of your AWS S3 bucket. The URL will be used to in the API response to give you the correct URL to downlaod your generated screenshots.

If you don't want to use AWS you can keep the AWS_ values empty and set the SCREEENLY_DISK value to public.

Set up Database

Next we need to set up the database with the required tables. This is quite easy and can be accomplished by running a console command.

1.Click on "More ⇕" in the upper right corner and select "Run console" from the dropdown. 2. Run the command php artisan migrate --force in the console.

In the output of the console, you should see something like the following. You can close the console window, if you the text "Process exited" is shown in the lower left corner.

Migrating: 2014_05_24_082330_create_users_table
Migrated:  2014_05_24_082330_create_users_table (21.82ms)
Migrating: 2014_05_24_082458_create_api_log_table
Migrated:  2014_05_24_082458_create_api_log_table (20.05ms)
Migrating: 2014_10_12_100000_create_password_resets_table
Migrated:  2014_10_12_100000_create_password_resets_table (14.32ms)
Migrating: 2015_07_08_211146_create_api_keys_table
Migrated:  2015_07_08_211146_create_api_keys_table (23.38ms)
Migrating: 2016_09_03_184856_add_auth_fields_to_users_table
Migrated:  2016_09_03_184856_add_auth_fields_to_users_table (110.25ms)
Migrating: 2019_08_19_000000_create_failed_jobs_table
Migrated:  2019_08_19_000000_create_failed_jobs_table (12.87ms)
Migrating: 2021_01_18_180815_add_ip_address_column_to_api_log_table
Migrated:  2021_01_18_180815_add_ip_address_column_to_api_log_table (6.09ms)
Migrating: 2021_01_20_193343_create_sessions_table
Migrated:  2021_01_20_193343_create_sessions_table (29.02ms)

Now, click on "Open app" in the Heroku dashboard and you should be able to see your very own screeenly instance. Click on "Take Screenshot" in the navigation and click on "Create Screenshot" to test that screeenly works.

You can now also create an account to generate an API key.

Create Amazon S3 Bucket to store screenshots forever

As mentioned in the beginning, Heroku uses an ephermal filesystem. This means that the screeenly app you've just deployed, will not store the generated screenshots forever. The screenshot will disappeare in a matter of seconds.

If you rely on the path value in the screeenly API response you will need a persistent filesystem like AWS S3. If you use the base64 value of the API response, skip this step.

I will not go into detail on how to create an AWS S3 bucket. I rather point you to the documentation of AWS:

• Create an AWS S3 bucket through the S3 console
• Update the "Config Vars" AWS_BUCKET, AWS_DEFAULT_REGION and AWS_URL accordingly
• Create a new IAM user by heading to the IAM Users Page. Create a new User and give it the AmazonS3FullAccess permissions.
• Copy and paste the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to your "Config Vars" in Heroku. This gives screeenly the power to upload screenshots to S3.
• As the final step, update the SCREEENLY_DISK to s3

If you now use the screeenly API to generate a screenshot, the screenshot should be uploaded to AWS S3. The path in the API response should also have a URL which points to your AWS S3 bucket.

Outro

Congrats! You've successfully deployed your own version of screeenly! 🎉

Footnotes

Heroku Free Tier

The free tier of Heroku isn't suited for real-world production apps which you rely on 24 hours per day.
However, it works well for apps like screeenly which you only might need a couple of times per day or even per week or month.

Help I'm stuck!

Please DO NOT open an issue with a problem related to Heroku deployment. Open a discussion thread instead.

Support in General

Support for this version of screeenly is limited. Please don't email me directly with your question. Always use the discussions feature of GitHub!