Trigger workflows from APIs, on a schedule, or on demand. API calls are easy with authentication handled for you. Add durable delays that survive server restarts.

API Hero

apihero

I've run where someone asked how to integrate their own GraphQL API with a third-party (Shopify) GraphQL API. across a post on reddit In a nutshell, they are building their own GraphQL API and want to integrate it with Shopify's GraphQL API. What sounds like a simple task, is actually quite complex. They seem to have some experience in the field, so they identified the biggest problem right away: When combining multiple GraphQL APIs, how do you protect certain fields for different groups of users (role-based-access) and what's the right way of injecting different credentials depending on the user and origin? There are several methods of combining multiple GraphQL APIs, stitching, wrapping, federation and composition are the most common ones. We'll have a look at the three of them, how they can help solve the problem (or not) and what the differences are. What is GraphQL Schema Stitching? GraphQL Schema stitching is a technique that allows you to combine multiple GraphQL APIs into one. It allows you to combine a set of heterogeneous APIs that don't know about each other. The result is a single combined GraphQL Schema that can be queried by a single GraphQL endpoint. What's great about this is that as a developer, you can now interact with both APIs as if they were one. Additionally, schema stitching allows you to build "link" between the two schemas. This means that you can query Products from the Shopify API, and "join" them with reviews from your own API. What are the downsides of Schema Stitching? While schema stitching is a great way to combine multiple GraphQL APIs, this approach also has some downsides. First, when stitching multiple GraphQL APIs together, you might run into naming conflicts. The more APIs you combine, the more likely it is that you'll run into naming conflicts. Naming conflicts can be resolved by renaming fields or types, but this can be a tedious task. So, it's not a show-stopper, but it's something to keep in mind. Second, schema stitching is a very manual process. If you want to add links between your schemas, you have to do this manually. Third, authentication and authorization get more complex when combining multiple GraphQL APIs. Implementing authentication and authorization for a single API is already a complex task, but it's doable. As you own the API implementation, you can implement authentication in a way to "inject" the user object into the resolver context. Inside the resolvers, you're able to access the user object from the context and can use it to implement authorization. But how does this work if you don't actually own the API implementation? Shopify doesn't understand your user object, and the resolver is actually a "remote-resolver". Now imagine that, depending on the role of the current user, you want to allow them to use certain fields on the Shopify API, while regular users should not be able to access those fields. Additionally, you need to inject different credentials depending on the user and origin. This is where schema stitching gets really complicated. It's doable, by adding custom middlewares to intercept the requests and rewrite them, but it definitely shows the limits of schema stitching. We'll look at federation and schema composition later to see how they can solve this problem, better or worse. Finally, schema stitching comes with another "downside": Schema design, or the opposite. When you build a single GraphQL API, this API (hopefully) follows certain design principles. The way you name your fields, types and arguments should be consistent. When you look at the Schema, you can clearly see that it's one single API. Once you start stitching multiple GraphQL APIs together, you end up with an API that follows multiple design principles. There are many ways how GraphQL Schemas can differ from each other, like camel case vs snake case, plural vs singular for field names, input objects vs long lists of arguments, unions for responses to indicate known errors vs error codes in the error object and flat response objects. If you're using GraphQL as an "internal API ORM", this is fine. However, if you're exposing the GraphQL API to other teams or even the public, you might want to consider a better option than exposing your Frankenstein-stitched-API to the world. What is Schema Wrapping? In contrast to schema stitching, schema wrapping doesn't really combine multiple GraphQL APIs side-by-side. Instead, you're wrapping all 3rd party APIs under a single umbrella-API. What are the benefits of Schema Wrapping? The main benefit of schema wrapping is that you have full control over the API design and implementation. You can safely wrap the Shopify API without leaking any implementation details to the outside world. As you're the full owner of this API, you can implement authentication and authorization in a way that fits your needs. What are the downsides of Schema Wrapping? Full control and power over the API design and implementation is great, but this comes at a cost. Schema stitching has some manual parts, but a lot of the work is done automatically. With schema wrapping, you have to do everything manually. This means, you have to write all resolvers, all middlewares and all the glue code yourself. Additionally, you have to maintain the API implementation yourself. If you're using a 3rd party API, you have to make sure that you're always up-to-date with the latest changes. In terms of performance, schema wrapping will always run through two layers of resolvers. This can have a negative impact on performance. A single GraphQL API might be able to solve the N+1 problem using the dataloader-pattern. But when you're wrapping multiple GraphQL APIs, you might end up with inefficient execution plans where the dataloader-pattern doesn't work anymore. An example is when you fetch the current shopping cart from your own API, and want to fetch the current price of the products from the Shopify API. You'll end up making multiple requests for the nested price field. This nested field is not part of the "local" API, so the dataloader-pattern won't work here. What is Apollo Federation? Another option to combine multiple GraphQL APIs is to use Apollo Federation. Apollo Federation is a specification that allows you to combine multiple GraphQL APIs into one. Compared to schema stitching, federation is a more declarative approach. The goal of federation is to design a single GraphQL API that can be implemented by multiple services. Each service can be implemented by a different team, and each service can be implemented in a different programming language. But all services together form a single GraphQL API. What are the benefits of Apollo Federation? The main benefit over schema stitching is that you're more likely to end up with a consistent API design. Federation allows you to scale a landscape of GraphQL Microservices across multiple teams. What are the downsides of Apollo Federation? That said, federation doesn't really solve the problem of merging 3rd party APIs. While it's a great tool when all "Subgraphs" are under your control, it's not really a solution when you want to combine multiple 3rd party APIs. Shopify will most likely not respect your API design guidelines. Imagine you'd have to achieve consistent API design across all companies who expose their APIs publicly. It's not really feasible. So, while federation is a great tool, it doesn't really help us with this problem. What is GraphQL Schema Composition? So far, we've discussed the tradeoffs between the two possible approaches, schema stitching and schema wrapping, while we've dismissed federation as it solves a different problem. Schema wrapping, being the most expensive one to implement, is really only an option if you have to expose the API to the public. At the same time, schema stitching still clocks in relatively high in terms of complexity and maintenance. That's where schema composition comes in handy. Schema composition embraces the idea of . Naming conflicts are resolved using namespacing, allowing us to combine multiple APIs fully automatically. treating APIs as dependencies The way we've implemented schema composition at WunderGraph is that we're not actually exposing the composed GraphQL API. Instead, we're using GraphQL Operations as a tool to define our actual API, . GraphQL is simply the language to manage the (API) dependencies, but the resulting API is not a GraphQL API. a REST / JSON-RPC API That's why we call the resulting Schema the . It's virtual, because it only really exists during development. "Virtual Graph" Here's an example of how a GraphQL Operation in a composed virtual graph looks like: query (
  $continent: String!
  # the @internal directive removes the $capital variable from the public API
  # this means, the user can't set it manually
  # this variable is our JOIN key
  $capital: String! @internal
) {
  countries_countries(filter: { continent: { eq: $continent } }) {
    code
    name
    # using the @export directive, we can export the value of the field `capital` into the JOIN key ($capital)
    capital @export(as: "capital")
    # the _join field returns the type Query!
    # it exists on every object type so you can everywhere in your Query documents
    _join {
      # once we're inside the _join field, we can use the $capital variable to join the weather API
      weather_getCityByName(name: $capital) {
        weather {
          temperature {
            max
          }
          summary {
            title
            description
          }
        }
      }
    }
  }
} What are the benefits of GraphQL Schema Composition? The benefits of this approach are that you can combine multiple APIs in just a few clicks. The caller of the API doesn't even have to know that the API is composed of multiple APIs. This means, we're able to expose the JSON-HTTP API as one single API. Authentication and Authorization across all APIs can be handled in a single place. If some APIs should only be accessible to special users, like admins, you can apply role-based-access at the API Gateway level. Additionally, you can handle injecting credentials, like admin or super admin tokens from within the API composition layer. API Composition is designed for exactly this use case. For each origin, different rules might apply on how to authenticate against the API. If we're treating APIs as dependencies, we can implicitly handle authentication and authorization for each API. What are the downsides of GraphQL Schema Composition? The main downside of this approach is that we're not exposing a GraphQL API. Instead, we're exposing a JSON-HTTP API. However, I've found that this is actually more of a benefit than a downside. When deploying a GraphQL API to production, you're very unlikely to change the GraphQL Operations at runtime. So, if we're not changing the Operations, we don't really need to expose a dynamic API. We can simply expose a fixed set of GraphQL Operations in the form of a JSON-HTTP API. More and more tools emerge to "secure" GraphQL APIs. When you're hiding the GraphQL API behind a JSON-HTTP API, the security concerns are mostly gone. The real downside of this approach is that it doesn't work if your intention is to expose the API to the public. While most GraphQL APIs are used internally, if your use case is to expose the API to the public, you're better off using schema wrapping. How can you leverage GraphQL Schema Composition to join multiple GraphQL APIs? As described above, the complexity of adding more APIs to a composed API is constant: O(1). Compared to schema stitching, where the complexity is exponential: O(n^2), assuming that n is the number of APIs. This means, you can add as many APIs as you want to your composed API without any additional complexity. The more APIs you combine with schema stitching, the more edge cases, like naming collisions, you'll have to deal with. Here's an example of how to compose two APIs: // wundergraph.config.ts
const weather = introspect.graphql({
  apiNamespace: 'weather',
  url: 'https://graphql-weather-api.herokuapp.com/',
})

const countries = introspect.graphql({
  apiNamespace: 'countries',
  url: 'https://countries.trevorblades.com/',
}) Simply make sure that you're using different namespaces for each API. That's the power of thinking in "APIs as dependencies". How to use Schema Composition with Schema Stitching and Apollo Federation? One additional benefit of Schema Composition is that you can use it together with Schema Stitching and Federation. You're not forced to using one pattern exclusively. Why not build some GraphQL Microservices with Federation and use Schema Composition to join some 3rd party APIs on top? It's a great way to combine the best of both worlds, scaling your internal teams while still being able to leverage 3rd party APIs without manually stitching them together. When to use which approach? Now that we've discussed the different approaches, let's summarize when to use which approach. When to use Schema Wrapping? Schema wrapping is the most expensive solution to implement, but it's also the most flexible one. Wrapping 3rd party APIs is the right way to go when you want to expose the API to the public and don't want to expose the underlying APIs. When to use Schema Stitching? Schema Stitching allows you to combine multiple heterogeneous APIs in a semi-automatic way. It doesn't scale well in terms of number of APIs, but if it's a small number, it might work. Keep in mind that the resulting API doesn't follow a single set of design principles. When to use Apollo Federation? Apollo Federation is a great way to build GraphQL Microservices. It works best when you have full control over all the APIs, which is usually the case when all API owners belong to the same company. In terms of integrating 3rd party APIs, federation is not the right approach. When to use GraphQL Schema Composition? Schema Composition or thinking in "APIs as dependencies" is the right approach when you need to compose a large number of APIs and want to expose the "API Composition" as a single API. Schema Composition can be used together with Schema Stitching and Federation, allowing you to combine the best of all worlds. Conclusion In this article, we've discussed the different approaches to combine multiple GraphQL APIs. Depending on your requirements, you might want to use one approach over the other. If you're interested in learning more about GraphQL Schema Composition, here's an , and another one , as we've seen in this article. example using federation combining country and weather data WunderGraph Cloud is coming soon! WunderGraph Cloud is a hosted Serverless (GraphQL) API Gateway that's currently in the works. It allows you to create API compositions locally and deploy them to the cloud in less than 30 seconds. We're looking for early adopters to help us shape the product. If you're interested, and be amongst the first to try it out for free! please sign up for the private beta

Stitching, Integrating, Composing & Federating Multiple GraphQL APIs 

A couple of years ago Github launched a neat “hidden” feature (seems like it’s still somewhat hidden these days) which allowed you to create a special kind of repository in your account. So you see, Github allows you to create this special repository and the README for this repo, acts as the landing page for your profile. You can read more about it in this by Github. official blog post You can share information about yourself with the community on GitHub.com by creating a profile README. GitHub shows your profile README at the top of your profile page. A Hello-World README page 👓 It’s pretty simple to whip up a bare-bones profile page. All you need to do is create this special repository named after your username and add a README page to it. Make sure to make this repository and for starters, go ahead and check the “Add a README file” box while creating the repository. public The newly created repo will contain a templated README courtesy of Github and Bob’s your uncle! Wow, this was pretty simple! 🍦 Well, yeah! But this is like a vanilla . It’s quick and it’s delicious. soft-serve But, that’s not what we really want now, is it? I for one want to have “some” sundae 😝 That’s not a typo, btw (Software Enginee 😅). That’s a dynamic piece of text. Lemme go over what all is there in and see if that is something that might interest you :) my Github profile Number of people who visited the profile. Profile Views — — Instagram, LinkedIn, Personal Website, Medium. Social badges — That’s a very simple text/banner generator that takes up any text you want and displays it in a typewriter fashion. Typewriter Text — A few bullet points about myself. Basic Information A daily programming quote that gets updated on the profile dynamically. Programming Quote of the day — — This article will also show up on the profile the next time you visit :) Latest Blog Posts Displays the song I’m listening to right now on Spotify! What’s Vibin? — — Most recent posts from an amazing Instagram account exploring Seattle, WA. Hey there, Seattle! — There’s a whole lot to unpack here so we’ll get to this later on in the article. Github Stats — That orange-colored card you see on the right. The Dev card The profile is not a static one but a dynamic one. Why is that? Because we use Github Actions — a whole lot of them — to update various parts of the README at different times of the day 🤘🏻. If this all sounds fun to you and you want to upgrade your Github profile as well, read on! Profile Views Counter 👁‍🗨 This one’s pretty simple to set up. All you need to do is, add the following line of code to your README wherever you want the counter to appear. ![](https://cdn.hackernoon.com/images/ckxz-5-f-75-v-00-z-00-as-638-qw-6-ofc.jpg) For more customizations to how this appears on your profile, refer to the official documentation . here Social Badges 🏅 For the badges, the was super handy. For ease of use, here are the relevant badge links from my profile. Feel free to change the “HANDLE” below and copy-paste the same to yours :) shields project We have the profile view counter and the badges set up. Woot Woot! Typewriter Text This . We’re not addressing the elephant in the room first! one’s also pretty simple to set up Head over to the website linked above and add whatever text you need along with your own customizations and finally, copy the markdown link for the same and add to your README. Easy peasy! Basic Information Nothing’s really fancy here. It’s just some pieces of information about myself. You don’t necessarily have to write about your technical accomplishments. Go crazy with what you write. I added my tennis profile, my pronouns, my hiking interests, in addition to where I work. The world is your oyster! In general, though, try to keep it anywhere from 8–10 bullet points. Any more than that and it will start to weigh on the reader. Programming Quote of the day 📜 There are multiple ways of adding a daily quote to your profile. If you’re feeling a little adventurous, you can write a script to call an external API that fetches the most recent quotes. The API being: https://programming-quotes-api.herokuapp.com/Quotes?count=2 And this is what the response looks like in the JSON format. You can then parse this response to fetch the quotes, however many you requested — count=2 in the API — and display them in the README in some format. In order to update the quotes regularly, you’ll need to add a Github Action that will run your script on a regular basis, maybe once each day, and update the README with the quotes. While this might seem the programmatically pleasing way to go, the final result might require a lot more effort as the presentation is equally important for the quotes. This seems more aesthetically pleasing than the quote itself, doesn’t it? If you think it does, then go ahead and follow the details in this . great repository Essentially, you need to add this image tag to your README file wherever you want the quote to appear. A new quote might appear whenever someone opens your profile page. This is the one-liner solution that in most likeliness, does the API calls and SVG rendering in the background and simply returns an image. Notice the “ ”. Well, quotes-github-readme.vercel.app that’s the hosted service linked to the Github repository that is running the quote image generator server or something. Pretty cool stuff! Daily Dev Card 🏋 Do you like to read? If the answer’s yes and your reading list includes some technical blogs from time to time, you might want to consider daily dot dev. Personally, I’ve added the chrome extension to get a regular feed of articles about topics I love to read about. Not really publicizing the platform but it is a great extension and platform. They generate an awesome dev-card for you based on your reading interests including all the badges, publications, topics you like, etc. The more you read, the better it gets. Follow this on how to add this dev-card to your profile. Most importantly, this is a dynamic card i.e. we use Github Actions workflow to update the card at frequent intervals. great blog post Latest Blog Posts ✏️ This one’s especially important if you’re an avid writer. There are a lot of platforms these days for writing and sharing both technical and non-technical content. There’s , , , (of course), and maybe your own personal website. Medium Dev.to Ghost.io hackernoon.com Basically, if you have any kind of RSS feed, you can hook it up with the README profile and keep updating it with the latest posts. How, you might ask? Via Github Actions of course :) This Github Action periodically replaces the following comments in your README with the hyperlinks to your recent 5 blog posts. Follow the steps mentioned to set this up. here Also, as a general rule of thumb, if you end up using any open source software, make sure to start it and share it! Goes a long way to help open-source developers. What’s Vibin? 🎧 🎼 I had the most fun setting this up. Before we get to the steps, one might ask why do we need Spotify’s now playing on a Github profile page? Well, why not? A developer is not just a bunch of commits, PRs, and open source projects. This is just an effort to make it more personal. Go ahead and add those Strava runs, Goodreads reading lists, anything you want really. This contains all the details on how you can set this up for your README. great repository I ran into trouble setting this up with Vercel or Heroku based on the steps . here The server is simply running the script “fetch_spotify.py” to get the currently playing song details for a user and then render an SVG based on a template. Instead of a hosted service, I decided to make use of Github Actions to call the same script every 5 minutes (can’t have a higher frequency) and do the exact same thing: generate an SVG from the currently playing song. Here are the steps I followed to set this up: Generated the Client Id, Client Secret, and the Refresh token as mentioned in the repository linked above. Copied the templates folder, , and templates.json spotify.py Renamed to fetch_spotify.py and made some changes to it. We don't want to run a flask server. Instead, it should be invokable via the main function. spotify.py Setup a new Github Actions workflow to call the script at a set schedule The script runs every 5 minutes and generates the “spotify.svg” file which gets placed in the repository root folder. From there, it gets picked up by the README file. Hey there, Seattle! 🏞 This might be a bit too much on the Github profile, but, I felt it’s worth showing off the beautiful place that Seattle is which is where work and home-away-from-home is currently for me :) For this, I wrote a Python script that uses the module to download the recent posts from a given Instagram account. We don’t need any sort of login functionality for accessing public accounts so make sure the account you choose is public. instaloader Again, the script is attached to a Github actions workflow so that we keep the profile updated with the latest Instagram posts from the account. You just need to set “INSTAGRAM_PUBLIC_HANDLE” as the secret for your Github Actions workflow to access and that’s about it :) The script looks something like this: The script downloads the recent 3 posts from the Instagram account and stores them in separate directories. Then, the README file can access them and display side-by-side. Github Stats 🍬 🍭 This is really the meat (vegan!) of the profile. It’s the place where you really show off what your open-source contributions amount to in a crisp, easy-to-digest fashion. Mine doesn’t look like much right now but it’s a work-in-progress. The first thing we have here is the Github stats card. This is a purview of all of your contributions so far on the platform like total stars, total PRs, commits, etc. Follow the steps mentioned to get the design you want for your card. here Next up, we have the top-languages card. This is something we tend to mention in our resumes. However, it’s better if Github compiles that for us based on our LOCs, right? From the same repository as before, to incorporate the top languages card in your profile. follow the steps Finally, there’s the big Github stats image that has a bunch of theatrical statistical stuff from your profile and contributions over the years. That comes from a separate repository and like all of these Github stats, that is also something that is dynamically updated. The stats and top languages above come from a hosted service, but, the image/card is updated by Github Actions. There’s a whole lot of customization around what you want and don’t want to include in the card and you can refer to the information mentioned for that. here Personally, I got a lot of inspiration for my profile from Waren Gonzaga. I also kinda copied the Github Actions for generating the stats card from their repository as well. Other Notable mentions That’s pretty much what all was needed to set up a great (rockstar? you tell me!) Github profile. There are a few other notable mentions that I’d like to point out though. is a great tool for beautifying your code snippets and adding them to your articles. The only downside is, they’re images and not scrollable like Github Gists or something. Carbon Next up me of the greatest, inspiring Github profiles. This is where I personally started to get some inspiration for my profile. is a brilliant collection for so is a great place to find some fun and interesting animated emojis that you can add to your profile. Slackmojis Finally, the footer for my profile README is this wave-like animation that keeps changing colors and gradients on its own. If this is something that interests you, head over to the link shared before ( . capsule-render) Thanks! If you’ve made it this far in the article, cheers to you! Thanks a bunch for reading :) to my repository. Feel free to fork and play around. Here’s the link

How to Make a Rockstar Github Profile README

, we explored how to automate the deployment of our Haskell app with Circle CI. Every time we push a branch, Circle CI will load our code onto a container, build it, and run any tests we have. We also configured Heroku to deploy our new code whenever the master branch passed the build. Last week Our system had a couple weaknesses though. First, it was a bit of a hassle that our configuration required us to download the Stack program every time. Setting up Stack required about half the commands in our Circle config! The second weakness was that we built our code twice on each deploy. First, the Circle container would build it. Then Heroku would also compile it. This week, we’ll solve these problems using Docker images. Using Docker Images Last week we used a vanilla Circle container. We can start simplifying our configuration by using a pre-existing Docker image instead. Remember the start of our section? It looked like this: build_project jobs:  build_project:    machine: true The keyword tells Circle to use an unconfigured Linux box. Since it had nothing on it, we needed to download and install Stack ourselves. However, Circle also allows us to use Docker images as the starting point for our machines. We’ll use an image from the . These each have a particular version of GHC installed, and the later ones also come with Stack. These images lag behind GHC releases a little bit. So we’ll use GHC 8.0.2, and update our file to use LTS 9.21, the latest version for this GHC. Here’s how we write our Circle configuration to use this image: machine Haskell Docker repository stack.yaml jobs:  build_project:    docker:      - image: haskell:8.0.2 Now we can radically simplify the rest of the file! Stack and GHC will be pre-installed, so we can remove all the steps related to those. We’ll also remove the caching step on the installed Stack directory. This leaves us with the following configuration file: version: 2jobs:  build_project:    docker:      - image: haskell:8.0.2    steps:      - checkout      - restore-cache:        keys:          - stack-work-{{checksum “stack.yaml”}}-\                       {{checksum “HaskellTestApp.cabal”}}      - run: stack setup      - run: stack build      - run: stack test      - save_cache:        key: stack-work-{{checksum “stack.yaml”}}-\                        {{checksum “HaskellTestApp.cabal”}}        paths:          - “.stack-work”

workflows:  version: 2  build_and_test:    jobs:      - build_project Making our Own Docker Image Now our builds are a little more efficient, but we haven’t solved the bigger problem in our system. In the rest of this article, we’ll use Docker to create a new image with our code built on it. Then we can push this image to Heroku instead of re-building our code with the buildpack. To do this, we’ll fold some of the existing Circle configuration work into Docker itself. To start, we need to define a at the root of our project. This file specifies the commands Docker needs to run to create an image with our code and run the server. Here’s what ours looks like: Dockerfile # Use the existing Haskell image as our baseFROM haskell:8.0.2

# Checkout our code onto the Docker containerWORKDIR /appADD . /app

# Build and test our code, then install the “run-server” executableRUN stack setupRUN stack build --test --copy-bins

# Expose a port to run our applicationEXPOSE 80

# Run the server commandCMD [“run-server”] The first important part is that we’ll “inherit” from the Haskell Docker image we were using on Circle with . Then we’ll run our setup command, and build the project. We’ll pass arguments to that will run the tests, and install our executables. Then, we’ll run the server off the container. FROM build Building Our Docker Image on Circle To actually save a Docker image on a remote repository, we’ll need to make a Docker account. We don’t need to create our own repository, since we’ll end up storing our image on a Heroku repository. We no longer need to run Stack commands as part of our Circle configuration. Docker handles them for us. We can go back to using a normal machine, as Docker also handles using the Haskell image. Here’s the core of our configuration on Circle: jobs:  build_project:    machine: true    steps:      - checkout      - run: echo $DOCKER_PASSWORD | docker login \                                     --username=$DOCKER_USERNAME \                                     --password-stdin      - run: docker pull \                               registry.heroku.com/$HEROKU_APP/web:$CIRCLE_BRANCH      - run: docker build -t \               registry.heroku.com/$HEROKU_APP/web:$CIRCLE_BRANCH      - run: docker push \               registry.heroku.com/$HEROKU_APP/web:$CIRCLE_BRANCH The key commands are obviously the four commands. First, we log into our Docker account using our credentials as environment variables. Next, we’ll pull the existing image off the Heroku image repository tied to our app. We don’t need to do anything to set this repository up, but we’ll need to configure the app to use it below. Then we build our container and tag it with our current branch name. As long as this succeeds, we’ll push this new image back to our Docker repository. docker Heroku Integration To use this image on Heroku, we’ll need to update the “Deploy” section of our app again from the dashboard. Instead of using Circle CI, we’ll use the Heroku registry option. Now our successful builds will push our code up to our Heroku registry. Then Heroku updates our app automatically! Plus, there will now be no need for us to rebuild the code on Heroku! There’s one more caveat though. To push and pull from the Heroku registry, we also need to login to Heroku from our circle machine. Circle CI version 2 doesn’t yet have built-in support for this, so it’s a little tricky. On our own machine, we would login to Heroku using the CLI with the command. But we can’t use that command with the way we can with Docker’s login command. heroku login stdin But we can replicate the ultimate result of logging in with a little script. Logging into Heroku creates a file called storing our credentials. We can write this script that will output all that information like so: ~/.netrc #! /bin/bash

cat > ~/.netrc << EOFmachine api.heroku.com  login $HEROKU_LOGIN  password $HEROKU_PASSWORDmachine git.heroku.com  login $HEROKU_LOGIN  password $HEROKU_PASSWORDEOF

heroku container:login We run the final command to actually connect to the repository. Note that the environment variable should use your Heroku API Key, NOT your Heroku password. We call the variable because the environment variable is special. It can cause problems with the CLI to have it set pre-maturely. heroku container $HEROKU_PASSWORD PASSWORD HEROKU_API_KEY With this script saved as , we can call it from our Circle script like so: setup_heroku.sh jobs:  build_project:    machine: true    steps:      - checkout      - bash .circleci/setup_heroku.sh      ... Now everything should work! Our app should be automatically deployed to Heroku without re-compilation! Conclusion We’ve now made our deployment process a lot more efficient. First we used a Docker Haskell image to avoid manually downloading Stack. Then we created our own Docker image off of this, and pushed it to a registry. Once we connected our Heroku app to this registry, we no longer needed to compile it there. Next week, we’ll conclude this series by using a similar process to push our code to AWS instead of Heroku. Now that you can deploy your code, you can make whatever Haskell apps you want! Download our to get some more ideas for libraries you can use in your apps. Production Checklist And if you’ve never used Haskell before, download our to get started! Beginners Checklist

Dockerizing our Haskell App

I would like to share a recent with bug bounties. I’ve been doing bug bounties for years and I just now am trying-out the big boys on the playground — and — and the experience is… well, different. experience bugcrowd.com hackerone.com The incentive is there, I guess, to be able to negotiate with someone which cares on delivery times and holding accountability against the firms you are assessing, but I never felt the need of involving a third party in the process, maybe because I’m not making a living out of it and doing it out of fun and genuine care since usually I’ve been discovering vulnerabilities on websites I’m already an active user on. The extra buck, T-shirt or mere mention on a Hall-of-Fame of some sort, is mostly for bragging rights. I’ll come back to some of my own two-cent level insights at the end of this post — but first, let’s go on and tell you about the vulnerability found on Heroku. What’s Heroku? is pretty amazing, actually. They have an integrated PaaS solution that allows developers host their apps on the cloud with maximum ease. Heroku Large as well as small companies are using Heroku non-stop, so I guessed that’s a good place for interesting vulnerabilities that might affect them all by spotting an organization-indifferent vulnerability. Login API call, Spot the Response Anomaly Heroku has several options of interfacing with their service. Web-based is pretty common usage and API follows. There is a Heroku Command Line Interface (CLI) tool which basically is a wrapper to API calls. I used the CLI tool in order to contact the site and started on messing with some inputs and after a time I focused on the login mechanism which looked pretty simple. It is based on a POST request, accompanied by and parameters. username password At first, when messing with the inputs I figured nothing really matters, I was hoping for an error output or any kind of response changes between real usernames against bogus ones. Even though I didn’t see any of those error text changes — there was one more subtle change in response. A login request looks something like that: POST HTTP/1.1Host: api.heroku.comUser-Agent: heroku-cli/5.2.39-010a227 (windows-386) go1.6.2Content-Length: 54Accept: application/jsonContent-Type: application/x-www-form-urlencodedAccept-Encoding: gzip https://api.heroku.com/login password=fjfjfjfj&username=bogus%40gmail.com And an appropriate response would be: HTTP/1.1 404 Not FoundCache-Control: private, no-cacheContent-Type: text/html;charset=utf-8Date: Mon, 29 Aug 2016 16:49:52 GMTRequest-Id: b3ca4a2c-1adf-4244-4cb0-17fbbc9deb06Server: nginx/1.8.1Strict-Transport-Security: max-age=31536000; includeSubDomainsVary: Accept-EncodingX-Content-Type-Options: nosniffX-Frame-Options: SAMEORIGINX-Runtime: 0.018023806X-Xss-Protection: 1; mode=blockContent-Length: 0Connection: keep-alive So, as said, nothing more than a 404, but on the other hand it is somewhat generous on it’s optional headers — “so what?” you might ask. That makes the whole difference. To be specific, the thing that caught my eye was the “ header. X-Runtime” From it’s name I could only guess what it is that I found. But it needed a bit more probing to be sure about it. Freeze, you bastard! First stop is looking at the 1,000,000th time at the HTTP RFCs, noting that there is nothing like it in there — so it must be something added by another component on the web server. A short scan revealed it is most probably derived by a server side component relying on Ruby/Rails. One of those projects, named , was first to come up in search, that is to say that we can’t be sure of whether that’s the Ruby code that is operating on the site, but we’ll take it as a test case which proved to be sufficient at the end. Rack For those of you that never heard of it (like myself), it’s GitHub page reads: Rack provides a minimal, modular, and adaptable interface for developing web applications in Ruby. By wrapping HTTP requests and responses in the simplest way possible, it unifies and distills the API for web servers, web frameworks, and software in between (the so-called middleware) into a single method call. Peering into it’s source code, the aberrant header is explained within : lib/rack/runtime.rb Now we can be sufficiently sure of our common-knowledge understanding of ‘X-Runtime’ meaning. It is referring to the time it took the operation to complete. Are you thinking of what I am thinking? To confirm this thought we have to get a larger test sample set against different mix of non-existent and existent user names on the system. And take note of timing differences and if there any distinguishable kind of delta. Existent user names inclusion yeilded the following timing annotation: X-Runtime: 0.093990008X-Runtime: 0.088857339X-Runtime: 0.09251876X-Runtime: 0.089843447X-Runtime: 0.091845765X-Runtime: 0.101260549 And when using non-existent user names (I’ve used the correct scheme of e-mail address, just to be safe): X-Runtime: 0.027787351X-Runtime: 0.018023806X-Runtime: 0.020997733X-Runtime: 0.021645124X-Runtime: 0.016645836X-Runtime: 0.021828831X-Runtime: 0.022211143 Old-School Side Channel Timing-Attack — ❤ All of this assessment is funneled into one final conclusion — There is a clear distinctive (~1 order-of-magnitude) difference in times between bogus and true user names on the system. Why is that even possible? Probably because of cryptography-related operations involved in the process of checking the password against it’s true hashed password. It is a by-the-book example of a Timing Attack. Once the server receives the parameters from the user it first checks the user to see if it is relevant, if it isn’t the operation comes to an end and respond the to the user. On the other case, if the user name is found to be relevant — it progresses forward-on to check the password given by the user against it’s local hashed copy of the password, which is a very intensive operation in contrast to the short trip to username-list that it followed. Because of that difference in operation time, we can perceive these distinctive routes. 404 Many applications are doing the same, but mostly because of latency it is somewhat harder to determine a definite conclusion upon a timing-based attack. In this case — the Ruby server is giving us all we need to get to this conclusion — all with one simple POST request. Cool! How to overcome the attack? This can be tackled on many levels. Since I’m not aware of Heroku’s considerations on keeping this header on, I will try to cover different approaches as there can be practical limitations of nearly each one of those. this is the most obvious recommendation as that’s the fault that led us to our conclusion, but this is just the end-result of something much inherent — the times computation might be observed on other, less straight-forward ways as the time of delay of the response. What I observed by counting round-trip time from sending a request until receiving a response was not something that is distinguishable by that alone. Runtime value can be used for debugging purposes and I have met with clients in the past that couldn’t just remove debug headers from all or even some subset of responses-if that’s the case they might modify it on a higher web-server level and make an effort to delete the generous line before compiling the final response. Very ugly patch indeed, but practicality overpower elegance sometimes. Remove ‘X-Runtime’ header from responses — relying on the assumption that Heroku has granular control over the process of user authentication, they might delay the process of checking username and password parameters to an extent of time. This wouldn’t necessarily be projected through X-Runtime if they decide on leaving that in place. Make all operation times equal — injecting random length delays into the process can, in effect, make those times erratic. The problem with this approach that on the greater scale in multiple checks over each guess you will get (assuming normal distribution of random-length delays) a central tendency towards a larger result. This, too, doesn’t necessarily be projected through X-Runtime. Add random timings to operations — This is considered a solution in case you are seeing this attack as something that is threatening a customer base as a whole and not as a targeted attack against a small subset of users. By this definition — you should be able to limit the amount of requests from a single source on a given time, this makes the efforts of the less-determined attacker redundant. This is not a bulletproof solution in any case since this usually circumvented by attackers which are using VPN, Anonymization network or a botnet to cover their tracks. Limit the amount of requests — Heroku/BugCrowd’s Response According to Bugcrowd’s terms — User Enumeration vulnerabilities are not in-scope, and they actually penalized me for that in -1 points (honestly, I should have known better. To my defense it wasn’t clear to me that there is a separate terms not only from the vendor but from BugCrowd as well that need to be adhered.) The thing is, as I mentioned before — that wasn’t my point, as many of my peers I wasn’t doing this for profit, I was trying to make a site I evaluated for using for my own needs and if happen to be, as in this case, prompt for vulnerabilities. Whether I get the bounty is the secondary objective, the thing that worried me is that because BugCrowd consider it out-of-scope doesn’t make this vulnerability something we shouldn’t discuss. The terms should be there to be defined that not everything is going to make you a small buck on the side, but once you find something that is out of scope for bugcrowd why should it be considered out-of-scope of mitigation for the vendor? security I truly don’t have anything against Heroku nor BugCrowd, they both are comprised of great, passionate people from my experience, but bureaucracy in this case contradicts progress and I wish those unwritten procedures should be taken care of for the benefit of our community.

“The Giving Ruby”—The Strange Case of User Enumeration on Heroku (Not Fixed)

How to Dockerize And Deploy Django Applications 

জ্যাঙ্গো অ্যাপ্লিকেশনগুলি কীভাবে ডকারাইজ এবং স্থাপন করবেন

So dockerisieren und stellen Sie Django-Anwendungen bereit

Cómo Dockerizar e implementar aplicaciones Django

Comment Dockeriser et déployer des applications Django

Django एप्लिकेशन को डॉकराइज़ और तैनात कैसे करें

Django アプリケーションを Docker 化してデプロイする方法

Django 애플리케이션을 Docker화하고 배포하는 방법

Como Dockerizar e implantar aplicativos Django

Как Dockerize и развертывать приложения Django

Django Uygulamalarını Dockerize Etme ve Dağıtma

Cách Dockerize và triển khai các ứng dụng Django

如何 Docker 化和部署 Django 应用程序

Part 1: Getting Going with the Starter Kit Businesses depend on Slack for communication and Salesforce for data management. As one might expect, conversations in Slack don’t always correlate to changes in Salesforce records. Being able to share data between these two services can increase team productivity by eliminating the need to switch between them. In December of 2021, Salesforce produced using their APIs. Building on top of any platform can be intimidating: You have to learn about how authentication works, the methods you can call, the events you can listen for, and so on. Slack has and an SDK, , which reduces a lot of boilerplate logic, getting you more quickly from an idea to an actual app. a video series explaining how to build Slack Apps excellent documentation Bolt The folks at Salesforce have done one better. Taking into account Bolt’s development principles and tooling, they developed the . It’s an opinionated scaffolding framework designed to make it easy to build Slack Apps that integrate with Salesforce data. Slack Starter Kit In this series of posts, we’ll show you how to use the Slack Starter Kit and Bolt to create an application that allows users to view and change Salesforce records—entirely in Slack. By the end of this series, we’ll have a fully functional Slack app that communicates with the Salesforce platform. In this first post, we’ll go through the SDK and set up your development environment for future work! Prerequisites Before we begin, make sure you have the following software installed on your machine: —this is a tool designed by Salesforce to simplify platform interactions. The sfdx CLI A recent version of (>= 14.0) Node The , as well as an existing Heroku account Heroku CLI A Slack workspace where you can install Apps An existing Salesforce Dev Hub We’ll first create a Slack App, which will provide us with tokens and other Slack-specific information we’ll need before building our app. To do that: Navigate to and click . https://api.slack.com/apps Create New App In the prompt that pops up, select . From scratch Set the name of the App to , and choose a workspace where the App can be installed. SFDCContactEditor That’s it! If you scroll down, you’ll see your App Credentials. We’ll be referring to these in the next section. On the left side nav bar, click on App Manifest. Your App Manifest defines some metadata about your app, such as the permissions it requests and the events it handles. Paste the following YAML into that box, overwriting what was there by default: _metadata:
  major_version: 1
  minor_version: 1
display_information:
  name: SFDCContactEditor
features:
  app_home:
    home_tab_enabled: true
    messages_tab_enabled: false
    messages_tab_read_only_enabled: true
  bot_user:
    display_name: SFDCContactEditor
    always_online: true
  shortcuts:
    - name: Whoami
      type: global
      callback_id: who_am_i
      description: shows Salesforce org details
oauth_config:
  scopes:
    bot:
      - chat:write
      - chat:write.public
      - commands
      - users:read
settings:
  event_subscriptions:
    request_url: https://heroku-app.herokuapp.com/slack/events
    bot_events:
      - app_home_opened
  interactivity:
    is_enabled: true
    request_url: https://heroku-app.herokuapp.com/slack/events
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false Click . If you get an error about a URL being unverified, don’t worry—we’ll address that soon! Save Changes Next, clone the , and then navigate to the directory: Slack Starter Kit scripts git clone https://github.com/developerforce/salesforce-slack-starter-kit
cd salesforce-slack-starter-kit/scripts Install the dependencies there with ; then pop up a folder, and install those dependencies: npm install npm install
cd ..
npm install Walking through the Salesforce Starter Kit With the Salesforce Starter Kit available and its dependencies installed, it’s time to take a look at what the Starter Kit can do. The primary goal of the Starter Kit is to get your environment set up for building, testing, and deploying a Slack App that integrates with Salesforce. It does this by: Setting up a Salesforce scratch org Setting up and deploying a sample application to Heroku Using Bolt to abstract away details with authentication Setting up a project structure that favors convention over configuration Let’s see this in action. First, make sure you’re authenticated to your Salesforce Dev Hub by running . Then, run , and a CLI prompt will take over. sfdx auth:web:login node scripts/deploy.js You’ll be asked to provide some information: For the Heroku App Name, we’ll use . Make sure to select a unique name for your Heroku App, since app names need to be unique across all Heroku apps. sfdc-contact-editor For the Slack Bot Token, go to the OAuth & Permissions page in your Slack App overview, and copy-paste the Bot User OAuth Token into the terminal. For the Slack Signing Secret, go back to the App Credentials section of the Basic Information page on Slack’s site. Copy-paste the provided signing secret into the terminal. Provide the name of your existing Dev Hub alias. You can name your scratch org anything you like—the default of is fine! scratchorg Now, grab a beverage and sit back, as the Starter Kit sets up some accounts for you. It creates a brand new scratch org and a new Heroku app, and it defines some essential environment variables for the deployed app to use. : if you receive a failure about a missing , make sure you have . If you receive a failure about a missing public key or permissions when pushing to Heroku, run . Note OrgCreateCommand enabled Dev Hub heroku keys:add After some time, you’ll receive the following message: Done deploying Heroku app sfdc-contact-editor In order to verify that the application was configured and deployed, you can perform two separate steps. First, run the following command in your terminal window: sfdx force:org:open Navigate to , and you should see an app titled “Connected App For Slack.” This is the Salesforce platform policy that the Starter Kit created for your Slack app. Manage Connected Apps Next, go to , and you should see your brand new app listed there. https://dashboard.heroku.com/ Now that we have a production version of the app available, we’ll need to make one more change to our Slack configuration to unite the two. Open up your and find the lines that identify your Heroku endpoint: App Manifest two request_url: https://heroku-app.herokuapp.com/slack/events Replace the placeholder with the actual name of your Heroku app. Click . Slack will inform you that your request URL isn’t verified; click to make that happen! heroku-app Save Changes Verify Watching it work Let’s try interacting with our app to ensure that everything is wired up correctly. Remember: we have a production app running on Heroku which intercepts a user’s Slack activity and communicates with Salesforce. We haven’t added any of our own functionality yet; everything was preconfigured by the Starter Kit. First, . You’ll be asked to authenticate with Salesforce; click on the button to do so. Then, head into any Slack room, and run the : add the app to your Slack workspace whoami shortcut provided by the app Voila! Next, let’s take a quick look at what’s inside the Starter Kit. Open up the project in your IDE, and navigate to the folder. In here, there’s a file called . This is where the entirety of the Salesforce authentication takes place. We don’t need to do anything to this file, but it’s useful to know just how much is being abstracted away for us. salesforcelib connect.js Next, open up the folder. This folder contains all the app logic for listening to and responding to events from Slack. Open up , then . This file contains all of the functionality for the shortcut we just issued. There are two important things to point out: listeners shortcuts whoami.js The first method called in the function is . Slack requires that an app acknowledge an event within three seconds of it occurring, and is responsible for sending that message to Slack. ack ack In the next line— —we fetch our connection information from Salesforce. const conn = context.sfconnection Lastly, let’s take a look at the user-interface folder. As you might have guessed, this folder contains all of the UI definitions for our Slack app. (We’ll definitely take a deeper look at how to build a UI in our next part.) Inside here, open up the modals folder, then open . The Starter Kit takes care of the actual definitions for designing and prompting the UI modal we saw. The only thing we can customize is the box text. Let’s get cheeky and add an exclamation point to the end of this sentence: whoami-response.js Successfully connected to salesforce instance ${instanceurl}. Authenticated with user ${username}! Let’s deploy this app live to production! If you don’t know how, you should familiarize yourself with . Put simply, however, all we need to do is push our committed change to our Heroku remote: this article on deploying to Heroku $ salesforce-slack-starter-kit (main): git add apps/slack-salesforce-starter-app/user-interface/modals/whoami-response.js
$ salesforce-slack-starter-kit (main): git commit -m "Add an exclamation point" 

> salesforce-app@1.0.0 precommit
> lint-staged

✔ Preparing...
✔ Running tasks...
✔ Applying modifications...
✔ Cleaning up...
[main 44aac80] Add an exclamation point
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git push heroku main When Heroku is finished, you can return to Slack, issue the same shortcut, and see your new change live. whoami Learning more Whether you’re an experienced developer or just getting started, the Slack Starter Kit can save you so much time. In our short time together, we were able to: Create a new Salesforce environment Create a new Slack app Deploy the Slack app to Heroku Wire up Slack, Heroku, and Salesforce Issue a Slack shortcut and see the results The Starter Kit has essentially solved a lot of problems around authentication and API tokens by automating much of this for us. Every app will need these aspects configured, and since the Starter Kit has made these repetitive processes easier, we can now concentrate on what matters most: developing an incredible Slack app. With this foundation established, we’re ready to continue building on it in our next installment! We’ll look a little closer at the architecture of the Starter Kit, and add a new command of our own. Also Published . here

How to Build a Slack App That Changes Salesforce Records Within Slack

Heroku and CircleCI : Automated CI/CD Process for a NuxtJS

There’s a plugin out that makes it easy to use Sanity as a headless CMS for a JAMstack website built with . It’s pretty easy to install and integrate with exciting projects on . If you’re new to the static site generator, or want to test the plugin out, we made , with people, projects, a blog, and some info pages. In this tutorial we’ll show how to set it up, and how to run Gatsby in mode on a web server, to get a real-time online preview of content changes. new source Gatsby.js Gatsby a full company website and a headless CMS example development The example is a monorepo, containing both the configuration for Sanity Studio, where you’ll be editing content, and the Gatsby built website. It’s also configured to be deployed straight onto or . You can create a new free Sanity project within it, and be up and running in minutes. Web development in the age of is truly fantastic! Netlify Now JAMstack We feel safe that you can take our company website example, and make it your own. Clone or fork the repository on Github Go to the and clone, or fork it from there. You can also run this in your terminal in the folder you keep your web-projects (replace the URL with your own if you forked the project): example repository on GitHub git clone cd example-company-website-gatsby-sanity-combo https://github.com/sanity-io/example-company-website-gatsby-sanity-combo.git Install the Sanity CLI It’s convenient to have the Sanity CLI when working with projects like this, and it doesn’t take long to install. Run the following npm command in the command line: npm install --global @sanity/cli Install dependencies This example use ( ) for dependencies, you can also use yarn if you prefer that: node package manager npm ~/example-company-website-gatsby-sanity-combonpm install Set up Sanity.io as a headless CMS ~/example-company-website-gatsby-sanity-combonpm run init Run this command after the install script is finished. Follow the CLI’s instructions to create a Sanity.io project for the website. We recommend setting the dataset to (you can change it to private afterward if you prefer). A is where all you store all your content, kind of like a database. You can have more than one dataset. For example if you want a content test bed for development. public dataset The command also deploys a GraphQL API for your Sanity project (Sanity supports both and GraphQL). The Gatsby source plugin for Sanity uses the GraphQL schema definition to prevent types and fields missing from Gatsby’s templating API. As far as we know, this is the only plugin that helps you with that – it's pretty practical! npm run init GROQ Start the local development server In your project folder you have two folders: and . studio web The studio folder is where you’ll find the configuration files for the Sanity Studio, which is an open source editor for your content, built with JavaScript and React. It connects to the hosted API and is real-time, like you have in Google Docs. You can host the Studio anywhere you can host an HTML-file. In the folder you'll find the configuration files for all the types and fields. You can tweak and change these later if you want to, but we'll let them be for now. studio/schema The folder holds a Gatsby website, with everything you need set up to render the content managed with Sanity. If you're new to Gatsby, we recommend their to learn the basic ideas. web comprehensive documentation You can start both development servers for the Studio and the Gatsby frontend with a single command: ~/example-company-website-gatsby-sanity-combonpm start The studio runs on , and the website on . If you open the website you’ll be met with an error message. That’s because it needs some content to build. So start by opening the studio and log in. localhost:3333 localhost:8000 Go to and and fill in at least the names. Make a blog post (just some mock content is fine), a project, and some of the other stuff as well. You should give both your blog- and project entries a , a and preferably a date (in the past). Remember to publish the changes (the blue button down left). Although all changes instantly sync with the hosted backend, they won’t appear in the public API without being published. Site Settings Company Settings title slug Published at Now you probably need to restart the development server, to get Gatsby to build with the new changes. will quit the current process, and to start it again. ctrl + C npm start Try out watch mode for Gatsby If you look at the file called , you'll see the following entry in the plugins section: gatsby-config.js {  resolve: 'gatsby-source-sanity',  options: {    projectId,    dataset,    // To enable preview of drafts, copy .env-example into .env,    // and add a token with read permissions    token: process.env.SANITY_TOKEN,    watchMode: true, We have enabled , which means that Gatsby injects content changes on the fly, without you having to reload the development server, or refresh the browser. Few other source plugins do this. What's even cooler, is that other people can sit in the same studio, and edit content, and that too is instantly reflected on the frontend development server. The plugin only get access to published changes by default, but try editing something (maybe add an image to the first blog post), push and see if it updates in the frontend. watchMode Publish Add token to see all changes In the plugin, you maybe noticed and . With a with read privileges you give Gatsby access to unpublished documents, such as drafts. When is set to , Gatsby will use the draft version of a document if it has access to it. You'll need to save a read token in a file called in the web folder to enable this: token: process.env.SANITY_TOKEN overlayDrafts: true token overlayDrafts true .env ~/example-company-website-gatsby-sanity-combo/webcp .env-example .env Now you can go to (Manage -> Settings -> API), and . Give it a nice descriptive label, and only read rights. Copy it, and paste it in the .env file: https://manage.sanity.io/projects/<YourProjectId>/settings/api Add New Token ~/example-company-website-gatsby-sanity-combo/web/.envSANITY_TOKEN="YourToken" To load the token into Gatsby, you’ll need to restart the local development server again. It will be worth it though. Get your Gatsby site on the web with Netlify Maybe you want to tweak the frontend a bit, change the CSS, or make some adjustments. At some point you want to share it with the world though. We recommend that you put your project on GitHub. If you forked it, commit and push your changes. If you cloned it from us, on how to get a local git repo on GitHub. follow these instructions When it’s on GitHub, head over to Netlify and sign up or log in. If you choose from Git and find the repository you just updated, everything is set up and ready, thanks to the file in the project. Likewise, if you prefer (or want to use both for ultimate redundancy), you can run in the root folder of the project. New site netlify.toml Zeit’s now npm run now-deploy To quickly deploy the Sanity studio, run in the folder and choose a hostname. Now you can invite two additional users for free on the forever-free developer plan. If you need more, it's $10 per user on the pay-as-you-go on the same plan. Gatsby only uses 2 API request to build the whole site. One for all your content, and one for the schema. So you will get great mileage with a Gatsby website. We dig it! sanity deploy studio with our free plan Trigger new Netlify builds on content changes Netlify triggers new builds when you push commits to a branch that it monitors. The content, however, is not committed to Git. Fortunately, there are other ways of triggering builds, one of them is using webhooks. If you host your site on Netlify, you can go into -> and scroll down to . Choose , give it a name, and point to the branch you want to build from. Copy the URL, and return to the terminal: Settings Build & Deploy Build Hooks Add build hook ~/example-company-website-gatsby-sanity-combocd studiosanity hook create? Hook name: netlify? Select dataset hook should apply to: <yourDataset>? Hook URL: https://api.netlify.com/build_hooks/<someId> Now Netlify triggers a new deploy of your site everytime you publish some new content edits. BONUS: Content preview online on Heroku by Andreas Keller popped up in our feed. He has figured a way to run Gatsby on a development server on Heroku, hence making it possible to get that watch mode with live previews experience on the web. Which is nice if you have editors that can’t be expected to run a local development server in the terminal. Let’s set it up with the Sanity source plugin to get an unparalleled preview experience! This helpful tutorial Install the Heroku CLI Follow to install the Heroku CLI. Run and log in or sign up. these instructions heroku login Tweak gatsby-config.js To get Heroku to play nice with the monorepo (it likes its apps in the root folder), we must install the gatsby-cli as a dev dependency in the root folder: ~/example-company-website-gatsby-sanity-combonpm install gatsby-cli --only=dev There are also other where you push the folder, but then you have to put in the and manually in , as these variables are imported from in the folder. ways of doing it web projectId dataset gatsby-config.js sanity.json studio Once you’re set, you should do the following: ~/example-company-website-gatsby-sanity-combo# create a new heroku appheroku create # set node to run in development modeheroku config:set NODE_ENV=developmentheroku config:set NPM_CONFIG_PRODUCTION=false # set the project id and dataset, found in sanity.jsonheroku config:set PROJECT_ID=YourProjectIdheroku config:set DATASET=YourDatasetName # add the read token to Heroku’s environment# make sure that the token isn't wrapped in quotation marksheroku config:set SANITY_TOKEN=$(cat web/.env|grep SANITY_TOKEN) # add the app configuration to run gatsby on heroku’s dynoecho "web: cd web && gatsby develop -p $PORT -H 0.0.0.0" > Procfile # add the changes to gitgit add Procfile package.json package-lock.jsongit commit -m"Add Procfile and deps for Heroku" # push it to herokugit push heroku master # open the app in the browserheroku open # check the logs to troubleshoot if things doesn't workheroku logs --tail This app runs on a free dyno that sleep after a time of inactivity, and it can take some minutes to start up again. You can of course run it on a paid dyno which gives you full uptime. We cannot guarantee that it will be very stable, since the development server isn’t built to actually host a website on the web. If it crashes, you can restart it with . heroku restart It’s pretty cool nonetheless, and undoubtedly useful when you want to give your web editors a way to preview their changes instantly, without having to wait for rebuilds. Originally published at www.sanity.io .

How to quickly set up a Gatsby.js JAMstack website with a headless CMS

In several different articles now, we’ve explored how to build web apps using Haskell. See for instance, our and our series. But all this is meaningless in the end if we don’t have a way to deploy our code so that other people on the internet can find it! In this next series, we’ll explore how we can use common services to deploy Haskell code. It’ll involve a few more steps than code in more well-supported languages! Haskell Web Series API integrations If you’ve never programmed in Haskell at all, you’ve got a few things to learn before you start deploying code! Download our for tips on how to start learning! But maybe you’ve done some Haskell already, and need some more ideas for libraries to use. In that case, take a look at our for guidance! Beginners Checklist Production Checklist Deploying Code on Heroku In this article, we’re going to focus on using the service to deploy our code. Heroku allows us to do this with ease. We can get a quick prototype out for free, making it ideal for Hackathons. Like most platforms though, Heroku is easiest to use with more common languages. Heroku can automatically detect Javascript or Python apps and take the proper steps. Since Haskell isn’t used as much, we’ll need one extra specification to get Heroku support. Luckily, most of the hard work is already done for us. Heroku Buildpacks Heroku uses the concept of a “buildpack” to determine how to turn your project into runnable code. You’ll deploy your app by pushing your code to a remote repository. Then the buildpack will tell Heroku how to construct the executables you need. If you specify a Node.js project, Heroku will find your file and download everything from NPM. If it’s Python, Heroku will install and do the same thing. package.json pip Heroku does not have any default buildpacks for Haskell projects. However, there is a we can use (star this repository!). It will tell our Heroku container to download Stack, and then use Stack to build all our executables. So let’s see how we can build a rudimentary Haskell project using this process. buildpack on Github Creating Our Application We’ll need to start by making a free account on Heroku. Then we’ll download the Heroku CLI so we can connect from the terminal. Use the command and enter your credentials. heroku login Now we want to create our application. In your terminal, into the directory that has your Haskell Stack project. Make sure it’s also a Github repository already. It’s fine if the repository is only local for now. Run this command to create your application (replace with your desired app name): cd haskell-test-app heroku create haskell-test-app \  -b https://github.com/mfine/heroku-buildpack-stack The argument specifies our buildpack. We'll pull it from the specified Github repository. If this works, you should be able to go to your Heroku dashboard and see an entry for your new application. You’ll have a Heroku domain for your project that you can see on project settings. -b Now we need to make a Procfile. This tells Heroku the specific binary we need to run to start our web server. Make sure you have an executable in your file that starts up the server. Then in the , you’ll specify that executable under the name: .cabal Procfile web web: run-server Note though that you can’t use a hard-coded port! Heroku will choose a port for you. You can get it by retrieving the environment variable. Here’s what your code might look like: PORT runServer :: IO ()runServer = do  port <- read <$> getEnv “PORT”  Run port (serve myAPI myServer) Now you’ll need to “scale” the application to make sure it has at least a single machine to run on. From your repository, run the command: heroku ps:scale web=1 Finally, we need to push our application to the Heroku container. To do this, make sure Heroku added the remote Github repository. You can do this with the following command: heroku git remote -v It should show you two remotes named , one for fetch, and one for push. If those don’t exist, you can add them like so: heroku heroku git:remote -a haskell-test-app Then you can finish up by running this command: git push heroku master You should see terminal output indicating that Heroku recognizes your application. If you wait long enough, you’ll start to see the Stack build process. If you have any environment variables for your project, set them from the app dashboard. You can also set variables with the following command: heroku config:set VAR_NAME=var_value Once our app finishes building, you can visit the URL Heroku gives you. It should look like . You’ve now deployed your Haskell code to the cloud! https://your-app.herokuapp.com Weaknesses There are a few weaknesses to this system. The main one is that our entire build process takes place on the cloud. This might seem like an advantage, and it has its perks. Haskell applications can take a LONG time to compile though. This is especially true if the project is large and involves Template Haskell. Services like Heroku often have timeouts on their build process. So if compilation takes too long, the build will fail. Luckily, the containers will cache previous results. This means Stack won’t have to keep re-downloading all the libraries. So even if our first build times out, the second might succeed. Conclusion This concludes part 1 of our Haskell Deployment series. We’ll see the same themes quite a bit throughout this series. It’s definitely possible to deploy our Haskell code using common services. But we often have to do a little bit more work to do so. Next week, we’ll see how we can automate our deployment process by incorporating . Circle CI Want some more tips on developing web applications with Haskell? Download our to learn about some other libraries you can use! For a more detailed explanation of one approach, read our series. Production Checklist Haskell Web Skills

For All the World to See: Deploying Haskell with Heroku

, we started our exploration of the world of APIs by integrating Haskell with Twilio. We were able to send a basic SMS message, and then create a server that could respond to a user’s message. This week, we’re going to venture into another type of effect: sending emails. We’ll be using for this task, along with the Haskell API for it. Last week Mailgun Hailgun You can take a look at the full code for this article by looking at the branch on our Github repository. If this article sparks your curiosity for more Haskell libraries, you should download our ! [mailgun](https://github.com/jhb563/HaskellApisSeries/tree/mailgun) Production Checklist Making an Account To start with, we’ll need a mailgun account obviously. Signing up is free and straightforward. It will ask you for an email domain, but you don’t need one to get started. As long as you’re in testing mode, you can use a sandbox domain they provide to host your mail server. With Twilio, we had to specify a “verified” phone number that we could message in testing mode. Similarly, you will also need to designate a verified email address. Your sandboxed domain will only be able to send to this address. You’ll also need to save a couple pieces of information about your Mailgun account. In particular, you need your API Key, the sandboxed email domain, and the reply address for your emails to use. Save these as environment variables on your local system and remote machine. Basic Email Now let’s get a feel for the Hailgun code by sending a basic email. All this occurs in the simple monad. We ultimately want to use the function , which requires both a and a : IO sendEmail HailgunContext HailgunMessage sendEmail  :: HailgunContext  -> HailgunMessage  -> IO (Either HailgunErrorResponse HailgunSendResponse) We’ll start by retrieving our environment variables. With our domain and API key, we can build the we’ll need to pass as an argument. HailgunContext import Data.ByteString.Char8 (pack)

sendMail :: IO ()sendMail = do  domain <- getEnv “MAILGUN_DOMAIN”  apiKey <- getEnv “MAILGUN_API_KEY”  replyAddress <- pack <$> getEnv “MAILGUN_REPLY_ADDRESS”  -- Last argument is an optional proxy  let context = HailgunContext domain apiKey Nothing  ... Now to build the message itself, we’ll use a builder function . It takes several different parameters: hailgunMessage hailgunMessage :: MessageSubject -> MessageContent -> UnverifiedEmailAddress -- Reply Address, just a ByteString -> MessageRecipients -> [Attachment] -> Either HailgunErrorMessage HailgunMessage These are all very easy to fill in. The is and then we’ll pass our reply address from above. For the content, we’ll start by using the constructor for a plain text email. We’ll see an example later of how we can use HTML in the content: MessageSubject Text TextOnly sendMail :: IO ()sendMail = do  …  replyAddress <- pack <$> getEnv “MAILGUN_REPLY_ADDRESS”  let msg = mkMessage replyAddress  …  where    mkMessage replyAddress = hailgunMessage      “Hello Mailgun!”      (TextOnly “This is a test message.”)      replyAddress      ... The type has three fields. First are the direct recipients, then the CC’d emails, and then the BCC’d users. We're only sending to a single user at the moment. So we can take the item and modify it. We’ll wrap up our construction by providing an empty list of attachments for now: MessageRecipients emptyMessageRecipients where  mkMessage replyAddress = hailgunMessage    “Hello Mailgun!”    (TextOnly “This is a test message.”)    replyAddress    (emptyMessageRecipients { recipientsTo = [“verified@mail.com”] } )    [] If there are issues, the function can throw an error, as can the function itself. But as long as we check these errors, we’re in good shape to send out the email! hailgunMessage sendEmail createAndSendEmail :: IO ()createAndSendEmail = do  domain <- getEnv “MAILGUN_DOMAIN”  apiKey <- getEnv “MAILGUN_API_KEY”  replyAddress <- pack <$> getEnv “MAILGUN_REPLY_ADDRESS”  let context = HailgunContext domain apiKey Nothing  let msg = mkMessage replyAddress  case msg of    Left err -> putStrLn (“Making failed: “ ++ show err)    Right msg’ -> do      result <- sendEmail context msg      case result of        Left err -> putStrLn (“Sending failed: “ ++ show err)        Right resp -> putStrLn (“Sending succeeded: “ ++ show rep) Notice how it’s very easy to build all our functions up when we start with the type definitions. We can work through each type and figure out what it needs. I reflect on this idea some more in this article on , which is part of our for newcomers to Haskell! Compile Driven Learning Haskell Brain Series Effify Email Now we’d like to incorporate sending an email into our server. As you’ll note from looking at the , I revamped the Servant server to use free monads. There are many different effects in our system, and this helps us keep them straight. Check out for more details on free monads and the Eff library. To start, we want to describe our email sending as an effect. We’ll start with a simple data type that has a single constructor: source code this article data Email a where  SendSubscribeEmail :: Text -> Email (Either String ())

sendSubscribeEmail :: (Member Email r)  => Text -> Eff r (Either String ())sendSubscribeEmail email = send (SendSubscribeEmail email) Now we need a way to peel the effect off our stack, which we can do as long as we have . We’ll mimic the function we already wrote as the transformation. We now take the user’s email we’re sending to as an input! Email IO sendEmail runEmail :: (Member IO r) => Eff (Email ': r) a -> Eff r arunEmail = runNat emailToIO  where    emailToIO :: Email a -> IO a    emailToIO (SendSubscribeEmail subEmail) = do      domain <- getEnv "MAILGUN_DOMAIN"      apiKey <- getEnv "MAILGUN_API_KEY"      replyEmail <- pack <$> getEnv "MAILGUN_REPLY_ADDRESS"      let context = HailgunContext domain apiKey Nothing      case mkSubscribeMessage replyEmail (encodeUtf8 subEmail) of        Left err -> return $ Left err        Right msg -> do          result <- sendEmail context msg          case result of            Left err -> return $ Left (show err)            Right resp -> return $ Right () Extending our SMS Handler Now that we’ve properly described sending an email as an effect, let’s incorporate it into our server! We’ll start by writing another data type that will represent the potential commands a user might text to us. For now, it will only have the “subscribe” command. data SMSCommand = SubscribeCommand Text Now let’s write a function that will take their message and interpret it as a command. If they text , we’ll send them an email! subscribe {email} messageToCommand :: Text -> Maybe SMSCommandmessageToCommand messageBody = case splitOn " " messageBody of  ["subscribe", email] -> Just $ SubscribeCommand email  _ -> Nothing Now we’ll extend our server handler to reply. If we interpret their command correctly, we’ll send the email! Otherwise, we’ll send them back a text saying we couldn’t understand them. Notice how our effect and effect are part of this handler: SMS Email smsHandler :: (Member SMS r, Member Email r)  => IncomingMessage -> Eff r ()smsHandler msg =   case messageToCommand (body msg) of    Nothing -> sendText (fromNumber msg)       "Sorry, we didn't understand that request!"    Just (SubscribeCommand email) -> do      _ <- sendSubscribeEmail email      return () And now our server will be able to send the email when the user “subscribes”! Attaching a File Let’s make our email a little more complicated. Right now we’re only sending a very basic email. Let’s modify it so it has an attachment. We can build an attachment by providing a path to a file as well as a string describing it. To get this file, our message making function will need the current running directory. We’ll also change the body a little bit. mkSubscribeMessage :: ByteString -> ByteString -> FilePath -> Either HailgunErrorMessage HailgunMessagemkSubscribeMessage replyAddress subscriberAddress currentDir =   hailgunMessage    "Thanks for signing up!"    content    replyAddress     (emptyMessageRecipients { recipientsTo = [subscriberAddress] })    -- Notice the attachment!    [ Attachment         (rewardFilepath currentDir)        (AttachmentBS "Your Reward")    ]  where    content = TextOnly "Here's your reward!”

rewardFilepath :: FilePath -> FilePathrewardFilepath currentDir = currentDir ++ "/attachments/reward.txt" Now when our user signs up, they’ll get whatever attachment file we’ve specified! HTML Content To show off one more feature, let’s change the content of our email so that it contains some HTML instead of only text! In particular, we’ll give them the chance to confirm their subscription by clicking a link to our server. All that changes here is that we’ll use the constructor instead of . We do want to provide a plain text interpretation of our email in case HTML can’t be rendered for whatever reason. Notice the use of the tags for the link: TextAndHTML TextOnly <a> content = TextAndHTML    textOnly   ("Here's your reward! To confirm your subscription, click " <>      link <> "!")  where    textOnly = "Here's your reward! To confirm your subscription, go to "       <> "https://haskell-apis.herokuapp.com/api/subscribe/"       <> subscriberAddress       <> " and we'll sign you up!"   link = "<a href=\"https://haskell-apis.herokuapp.com/api/subscribe/"      <> subscriberAddress <> "\">this link</a>" Now we’ll add another endpoint that will capture the email as a parameter and save it to a database. The effect very much resembles the one from the . It’ll save the email in a database table. Database Eff article type ServerAPI = "api" :> "ping" :> Get '[JSON] String :<|>  "api" :> "sms" :> ReqBody '[FormUrlEncoded] IncomingMessage    :> Post '[JSON] () :<|>  "api" :> "subscribe" :> Capture "email" Text :> Get '[JSON] ()

subscribeHandler :: (Member Database r) => Text -> Eff r ()subscribeHandler email = registerUser email Now if we wanted to write a function that would email everyone in our system, it’s not hard at all! We extend our effect types for both and . The function will retrieve all the subscribers in our system. Meanwhile the effect will send the specified email to the whole list. Email Database Database Email data Database a where  RegisterUser :: Text -> Database ()  RetrieveSubscribers :: Database [Text]

data Email a where  SendSubscribeEmail :: Text -> Email (Either String ())  -- First parameter is (Subject line, Text content, HTML Context)  SendEmailToList    :: (Text, ByteString, Maybe ByteString)    -> [Text]    -> Email (Either String ()) And combining these just requires using both effects: sendEmailToList :: (Member Email r, Member Database r) => ByteString -> ByteString -> Eff r ()sendEmailToList = do  list <- retrieveSubscribers  void $ sendEmailToList list Notice the absence of any calls! This is one of the cool strengths of . lift Eff Conclusion As we’ve seen in this article, sending emails with Haskell isn’t too scary. The API is quite intuitive and when you break things down piece by piece and look at the types involved. This article brought together ideas from both compile driven development and the Eff framework. In particular, we can see in this series how convenient it is to separate our effects with so that we aren’t doing a lot of messy lifts. Hailgun Eff There’s a lot of advanced material in this article, so if you think you need to backtrack, don’t worry, we’ve got you covered! Our will teach you how to use libraries like Persistent for database management and Servant for making an API. For some more libraries you can use to write enhanced Haskell, download our ! Haskell Web Skills Series Production Checklist If you’ve never programmed in Haskell at all, you should try it out! Download our or read our ! Haskell Beginner’s Checklist Liftoff Series

Mailing it out with Mailgun!

My goal is to make a workable piano. Once I’ve made the piano, I want to be able to build a database of playable songs, to be able to play along to. Nothing fancy, like rock band, but just a simple piano app with songs that you can play along with. If you want to follow along, here’s my workable prototype that we’ll be working toward: https://my-little-piano-app.herokuapp.com/ This is a fun project, and would be a fun little game to make for your kids. So let’s get started. I’m breaking this project up into 3 main components: 1 The HTML 2 The JavaScript 3 The Node.JS Database For the HTML, I originally wanted to make each key clickable, so the note would play on click. Later, I found that clicking each key achieved a much slower play, and an un-realistic sound. So I switched it up and assigned each sound to an individual key press. This allowed for more complex melodies and a more realistic sound. However, there are advantages to doing both, so in this tutorial, I’m going to show how you might go about doing either method, in case you want to follow along. 1a — HTML Keys If you decide to do clickable keys, one problem you might run into very quickly is that keys are complex shapes. They fit around each other like puzzle pieces. In HTML and CSS, it’s easy to make squares and rectangles, but slightly harder to make more complex shapes. Since I wanted to have mouseover effects, I needed to have each key separate. Instead of trying to do simple rectangles and then figure out alignment and z-indexes, I went with a much harder, and unnecessary approach: svg polygons. The “SVG” tag allows you to create shapes that would otherwise be impossible. So I created each key with specific points in the shapes I wanted. So that you don’t have to figure that out yourself, I’m including those elements here: <svg class="piano" height="230" width="1000"><polygon points="200,10 230,10 230,100 245,100 245,220 200,220 200,10" class="white"  id="c" data-key="65"/> <polygon points="245,100 260,100 260,10 275,10 275,100 290,100 290,220 245,220 245,100" class="white" data-key="83" id="d"/> <polygon points="305,10 335,10 335,220 290,220 290,100 305,100 305,10" class="white" data-key="68" id="e"/> <polygon points="335,10 365,10 365,100 380,100 380,220 335,220 335,10" class="white" data-key="70" id="f"/> <polygon points="380,100 395,100 395,10 410,10 410,100 425,100 425,220 380,220 380,100" class="white" data-key="71" id="g"/> <polygon points="425,100 440,100 440,10 455,10 455,100 470,100 470,220 425,220 425,100" class="white" data-key="72" id="a"/> <polygon points="470,100 485,100 485,10 515,10 515,220 470,220 470,100" class="white" data-key="74" id="b"/> <polygon points="515,10 545,10 545,100 560,100 560,220 515,220 515,10" class="white" data-key="82" id="key5"/> <polygon points="560,100 575,100 575,10 590,10 590,100 605,100 605,220 560,220" class="white" data-key="84" id="key5"/> <polygon points="605,100 620,100 620,10 650,10 650,220 605,220 605,100" class="white" data-key="89" id="key5"/> <polygon points="650,10 680,10 680,100 695,100 695,220 650,220 650,10" class="white" data-key="85" id="key5"/> <polygon points="695,100 710,100 710,10 725,10 725,100 740,100 740,220 695,220 695,100" class="white" data-key="73" id="key5"/> <polygon points="740,100 755,100 755,10 770,10 770,100 785,100 785,220 740,220 740,100" class="white" data-key="79" id="key5"/> <polygon points="785,100 800,100 800,10 830,10 830,220 785,220 785,100" class="white" data-key="80" id="key5"/> <polygon points="230,10 260,10 260,100 230,100 230,10" class="black" data-key="49" id="c_sharp"/><polygon points="275,10 305,10 305,100 275,100 275,10" class="black" data-key="50" id="d_sharp"/><polygon points="365,10 395,10 395,100 365,100 365,10" class="black" data-key="51" id="f_sharp"/><polygon points="410,10 440,10 440,100 410,100 410,10" class="black" data-key="52" id="g_sharp"/><polygon points="455,10 485,10 485,100 455,100 455,10" class="black" data-key="53" id="a_sharp"/><polygon points="545,10 575,10 575,100 545,100 545,10" class="black" data-key="54" id="key4"/><polygon points="590,10 620,10 620,100 590,100 590,10" class="black" data-key="55" id="key4"/><polygon points="680,10 710,10 710,100 680,100 680,10" class="black" data-key="56" id="key4"/><polygon points="725,10 755,10 755,100 725,100 725,10" class="black" data-key="57" id="key4"/><polygon points="770,10 800,10 800,100 770,100 770,10" class="black" data-key="48" id="key4"/></svg> Each polygon element is enclosed in the SVG tag and is defined by a series of points. Eacn polygon is also assigned a class, either black or white, corresponding to either black or white keys. Here’s the class styles I made for those: .white {fill:white;stroke:black;stroke-width:1;cursor:pointer;margin:2px;} .white:hover {fill:#9e9e9e;stroke:lightblue;cursor:pointer;stroke-width:1;outline: black solid 1px;} .black {fill:black;stroke-width:1;cursor:pointer;margin:2px;} .black:hover {fill:#515151;stroke:lightblue;stroke-width:1;outline: black solid 1px;} This defines the color and border, as well as the hover effects for each of the keys. Even though the black and white keys are next to each other on a keyboard, for me it was easier to group the black and white keys separately in the HTML document. Each polygon also has an ID. Most of the IDs correspond to the note associated with that polygon, starting at middle “C” all the way up to “B” of the next octave. You will also notice that in addition to an ID, each polygon element also has a data-key, with looks like this: data-key="80" What this does, is it associates each element with key press. Each key on the keyboard has a number. So at this point we could either click the key on the screen, or press a keyboard key to get the program to play a sound for us. However, since the user won’t instinctively know which keyboard key corresponds to each sound, I’ve included a display in the HTML to show that to the user. <div class="keysNotes"><h3>note</h3><h3>c</h3><h3>d</h3><h3>e</h3><h3>f</h3><h3>g</h3><h3>a</h3><h3>b</h3><h3>c</h3><h3>d</h3><h3>e</h3><h3>f</h3><h3>g</h3><h3>a</h3><h3>b</h3></div> <div id="keysshow" class="keysNumbers"><h3>keys</h3><h3>A</h3><h3>S</h3><h3>D</h3><h3>F</h3><h3>G</h3><h3>H</h3><h3>J</h3><h3>R</h3><h3>T</h3><h3>Y</h3><h3>U</h3><h3>I</h3><h3>O</h3><h3>P</h3></div> Then, in the CSS for these classes, I have the following: .keysNumbers {color: lightgray;font-size: 40px;font-family: monospace;font-weight: bold;z-index: 10;width: 740px;display: flex;flex-flow: row nowrap;justify-content: space-between;margin-left: 80px;margin-top: -110px;} .keysNotes {color: gray;font-size: 40px;font-family: monospace;font-weight: bold;z-index: 13;width: 740px;display: flex;flex-flow: row nowrap;justify-content: space-between;margin-left: 80px;margin-top: -150px;} This perfectly lines up the number and key display overlayed ontop of the on screen keys. Now, we need to bring in our audio files. I searched the internet, and found piano notes for each key I needed, except for F sharp, A sharp and both Fs. Since I had the other key sounds, I took those keys into a free program called audacity, and changed the pitch to the higher or lower pitch, and resaved the file to get the sound I needed. Audacity is a great tool for that, especially if you wanted to make something like a guitar player instead of a piano, but had limited recordings available to make your initial sounds. In any case, I don’t want you to have to go through all that trouble, so I’m providing the sounds I gathered here for free: https://www.dropbox.com/sh/buuc6h937s62vw2/AADHdRxmmDCfcatwjxvdwAvNa?dl=0 Next, I’m putting each of these files into the HTML with audio tags, and also including the key press codes we used earlier in the polygon elements. <audio data-key="65" id="c_octave1_audio" src="/middle_c.mp3"></audio><audio data-key="49" id="c_octave1_sharp_audio" src="/mid_c_sharp.mp3"></audio><audio data-key="83" id="d_octave1_audio" src="/middle_d.mp3"></audio><audio data-key="50" id="d_octave1_sharp_audio" src="/mid_d_sharp.mp3"></audio><audio data-key="68" id="e_octave1_audio" src="/middle_e.mp3"></audio><audio data-key="70" id="f_octave1_audio" src="/middle_f.mp3"></audio><audio data-key="51" id="f_octave1_sharp_audio" src="/mid_f_sharp.mp3"></audio><audio data-key="71" id="g_octave1_audio" src="/middle_g.mp3"></audio><audio data-key="52" id="g_octave1_sharp_audio" src="/mid_g_sharp.mp3"></audio><audio data-key="72" id="a_octave1_audio" src="/middle_a.mp3"></audio><audio data-key="53" id="a_octave1_sharp_audio" src="/mid_a_sharp.mp3"></audio><audio data-key="74" id="b_octave1_audio" src="/middle_b.mp3"></audio> <audio data-key="82" id="c\_octave2\_audio" src="/high\_c.mp3"></audio>  
<audio data-key="54" id="c\_octave2\_sharp\_audio" src="/high\_c\_sharp.mp3"></audio>  
<audio data-key="84" id="d\_octave2\_audio" src="/high\_d.mp3"></audio>  
<audio data-key="55" id="d\_octave2\_sharp\_audio" src="/high\_d\_sharp.mp3"></audio>  
<audio data-key="89" id="e\_octave2\_audio" src="/high\_e.mp3"></audio>  
<audio data-key="85" id="f\_octave2\_audio" src="/high\_f.mp3"></audio>  
<audio data-key="56" id="f\_octave2\_sharp\_audio" src="/high\_f\_sharp.mp3"></audio>  
<audio data-key="73" id="g\_octave2\_audio" src="/high\_g.mp3"></audio>  
<audio data-key="57" id="g\_octave2\_sharp\_audio" src="/high\_g\_sharp.mp3"></audio>  
<audio data-key="79" id="a\_octave2\_audio" src="/high\_a.mp3"></audio>  
<audio data-key="48" id="a\_octave2\_sharp\_audio" src="/high\_a\_sharp.mp3"></audio>  
<audio data-key="80" id="b\_octave2\_audio" src="/high\_b.mp3"></audio> You’ll probably want to include the audio files somewhere in your project, so that your HTML actually has access to them. Now that we have our audio, we could either code the keypresses or the onclicks to trigger the sound, or both. If we go the onclick route, our JavaScript could look something like this: function play(){       var audio = document.getElementById("audio");       audio.play();                 } Of course, replacing “audio” with whichever element we want to trigger the function. One side note, if we do nothing but this, you will run into a problem, where, if you click one button, and then a second, the second one won’t play until the first one has finished. So It’s nice to include a little extra in the function to stop any previous sounds, if a button is clicked, and then play only the sound that has been clicked. Which way is better? OnClick or KeyPress? That’s entirely up to you, but here are the arguments for both. OnClick is better if your goal is to help you or someone else learn the piano. And Here’s why: If your program relies on keypress, then the user is more often going to associate the key played with the letter displayed on the key, and not the letter associated with the note. So you could have the “C” key play the “middle C” and so forth, but that only works if you only have one octave. And then “C sharp” etc is also tricky. Eventually you’re going to have the user pressing “G” to play “high F” and “S” to play “A sharp”. You can see how this would get confusing for someone who is trying to learn the piano. OnClick allows the user to only associate the sound with the displayed letter, not the letter on the keyboard. However, clicking for each sound leads to a much clunkier piano sound, that isn’t very fluid or easy to play. In my opinion, neither is really a great tool for learning a musical instrument, which is why I went with the keypress approach, which is just more fun to play. I took some of the JavaScript for that from a drum Kit in one of Wes Bos’s projects, but it’s a great approach for this type of project. Here’s what it looks like: window.addEventListener('keydown', function(e) {const audio = document.querySelector(`audio[data-key="${e.keyCode}"]`);const key = document.querySelector(`.key[data-key="${e.keyCode}"]`);if (!audio) return;audio.currentTime = 0;audio.play();key.classList.add('active') Instead of having to get each element by ID, you simply listen for a keypress, and match it with the corresponding data-key, which we already have in our HTML. It plays the sound associated with that keypress, which we already have in our HTML as well. Finally, we’re saying if there isn’t any audio, play it, and we’re setting the audio.currentTime to 0, which helps with the wait I mentioned earlier, allowing the key pressed to play, and stopping any other sounds currently still playing. At this point you should be able to get your piano working either with keypresses or onclicks, whichever you prefer, and your piano is playable, hopefully. The only other thing I did extra was start a database of “sheet music” , so that you could select a song to play, and it will give you the notes for that song. You can see that in my example earlier. The hard part for this, is that, there isn’t an easy shortcut. If you create a similar database, you would have to manually add the notes for each song in there yourself. However, if anyone has a great way to transpose sheet music into JSON data…I’m all “ears”. Once I had the notes saved in a database, I could just make an api call when the song is selected and retrieve the notes associated with the selected song. You could also take it a step further, and let the song be played first, or any number of additional add-ons. Anyway, I hope you enjoy, and have as much fun with it as I did. If you have any feedback, please let me know!

Stories, News & Mentions about APIHERO

Apihero’s Stories on HackerNoon