Product Documentation
Product Documentation
Kodaris makes getting your site up and running simple with our base reference implementation, a fully functional commerce site from the start with sample category pages, product pages, search pages, checkout and more. By following these easy steps, you can immediately start tweaking your site – or go a few steps further and start your site from scratch.
In this guide, we’re going to take you through the four main steps of getting our reference implementation running:
To follow this guide, you’ll need:
Developing in Kodaris isn’t limited to VS Code and Bitbucket – you can use the IDE and version control of your choice – but they are the tools we’ll be using for this demonstration.
First, you need to import the reference implementation into a new repository so you can make the changes to the code as needed. Head to Bitbucket and choose “Import repository”:
On the next page, add the information about the new repository. You will need the URL to import from, which is the main Kodaris repo:
https://ajtate@bitbucket.org/kodaris/kodarisdemo-web.gitYou’ll also need your Bitbucket app username and password to clone the repo. Add it to a project (here “Kodaris”) and give the repo a name (we’ve called ours “kitty-web”). Hit “import repository” and you’ll clone the code:
You’ll now have a repository in Bitbucket with all the files for the Kodaris reference implementation:
You then need to clone this repository to your local machine. You’ll do this using VS Code. Open up a new instance of VS Code and, in the Command palette choose “Git:Clone,” then paste the URL of the repo (which you can get from the “Clone” button). It may ask you for a password – this is the app password that you create on your personal settings page.
Choose a destination directory and the code will be downloaded:
You’re now ready to start using this code with Kodaris.
Note: You can also start entirely from scratch without using the Kodaris reference code. In that case, just create an empty repository. However, you will need four files:
Next, let’s get a version of the code live on Kodaris.
In the last section, you cloned the repository into a “staging” branch in Bitbucket. To start using this code with Kodaris, you will need to create a “production” branch. This is the branch that Kodaris will always serve to your users (as you’ll see later, you can also create other branches for internal development before pushing to production).
In Bitbucket, head to “Branches,” and then “Create branch.” Create a new branch called “production”:
To make sure the code copied properly, you can quickly check by creating a new Pull Request from staging to production. It should say nothing has changed:
To install your production branch on Kodaris, you need to create a specific user in Bitbucket for this operation.
The Kodaris system needs a Bitbucket user and a Bitbucket API password. To do that, go to repository settings, then repository permissions, and add a user who can access this repository.
You can give them any permissions you want. For security’s sake we recommend that you dedicate a specific user with read access for use with your Kodaris system. That way, it’s an isolated user that only has read access and it’s not an actual user that can update and edit code or anything.
Accept the invitation (if you’re comfortable, you can skip the Bitbucket onboarding). What you need is the app password for this user from their personal settings page. You can label this what you want, but you must give this user “read” permission to the repository, as this is the permission Kodaris is going to use to access the repo:
When you press “Create,” you’ll be given a password. Save this, as it won’t be shown again.
With that password, you can then connect your code to Kodaris. Head to your Kodaris system URL and append “/operations” to access the Kodaris login page. Log in and go to “Development” and then to “Applications.”
These are all the applications that are installed on your Kodaris system. By default, you will see the Kodaris reference implementation installed. We want to install our own.
Before you get ready to install your own, however, you first want to open the Logs window. This allows you to watch the installation in case there’s any issues. It’s not a required step, but it’s nice to watch what is happening during the install.
Click on the install button in the top right corner, and choose “Website from bitbucket”:
You’ll then get a modal asking you for your Bitbucket information:
It’s going to ask for:
You can then hit install, switch over to the logs and watch the installation.
It's simply connecting to the Bitbucket repository and looping through all the files to copy them to the Kodaris system.
Once it’s finished, you will see that the reference implementation in Kodaris has been replaced by your implementation:
Now because you copied the Kodaris reference implementation, if you switch back over to the live site, nothing has changed:
You copied the files exactly, but it is in fact using your new repo now.
The next step is actually to start developing, customizing, and changing the code to what you want.
Before you can get started on developing on either production or another branch, you’ll want to install the Kodaris DevKit extension in VS Code.
This will allow you to develop straight on the site and test your changes. Just search for “Kodaris Development Kit” in the extensions marketplace, then click install.
You also need to define your permissions in Kodaris. In the Kodaris system, anybody who is labeled “employee” can’t develop and change the site. They have to have the right permissions. There are two different roles for development:
Now we can go back to VS Code and connect the repo to the Kodaris system. Open up the command palette and add a caret (>) to get the commands and search for “Kodaris: Add Remote.” Select that, add the URL of your Kodaris system, and then your Kodaris username (that has the web developer and/or production web developer roles attached), then your password.
You only have to do that once and your VS Code is connected to Kodaris. You can then use the Output pane to check the logs:
You can use these to troubleshoot any issues with your Kodaris development.
From here, there are two ways you can develop on Kodaris:
First, let’s switch to production. In the terminal, enter:
git fetch
git checkout productionYou are now working directly with the production branch. Any changes you make and push to the repository will affect website users.
Let’s make a minor edit to the welcome page. You can find the code for the welcome page in the welcome.ejs file. Go down past the styling to the main HTML, and add a small message before the slider:
Howdy from kitty!
Save the file, and you can see what has happened using the Kodaris DevKit Extension logs:
You have saved this change to Kodaris, which means the change has immediately gone live on the site:
This way of developing is great in the pre-launch phase when you need to iterate on your site fast and you won’t affect any users. But once you have a site live in front of customers, developing with branches is the better choice.
What if you want to control what you push out to live users? To do that, you want to develop with branches.
Let’s go back to our main development branch:
git checkout stagingFrom here, you can create a branch for your own development, then switch to it. For our example, we called it “mybranch1”:
git branch mybranch1
git checkout mybranch1When you first create a branch, it is only created in version control, not in Kodaris. To push it to Kodaris, open the command palette, type the caret, and then select “Kodaris: Push.” This will push your git branch into Kodaris.
If you open the output pane again, you can see all the files being uploaded to Kodaris, and the path is “mybranch1”:
Once it has pushed, you also need to tell Kodaris to use this branch. Head to your Kodaris URL and append “/services” to access your API documentation. On that page, switch to the User API:
Then you want to select the Customer API:
Near the bottom of the list there’s an endpoint called setCommerceLayout. This endpoint tells the website which branch you would like to see. Right now you’re seeing production, but you want to see “mybranch1,” so enter the name of the branch and click execute.
If you head back to the main site and refresh, you’re using “mybranch1” now. You’ll notice that you don’t see the new message you left on the “production” branch:
Let’s go back to your code and add a message in this branch:
Howdy from a branch!!
Saving this will immediately deploy it to Kodaris and you’ll see it live:
But, importantly, now it is live only for your view; you can see the changes being made on this branch to the site. You can make as many changes as necessary for your work before deploying them live.
If you are happy with your changes, all you need to do now is follow the usual version control flow to commit the changes, push to the remote repository, and then open a Pull Request to merge the changes with your public branch, which in this case is “staging”:
As an example, you can have multiple developers merging each of their personal development branches into your core dev branch during the week. Then, when ready, you can merge all of these changes into production:
To get Kodaris to deploy this latest version, head back into the Kodaris system to “Development,” then “Applications,” and click the “deploy” button for your code:
You can see the deployment happening in the logs:
Once that has completed, you can head over to the site again and you’ll see our new message, live for all your users:
That’s it! Let’s recap:
Now, it is up to you. You can change this code as much as you need for your own site and customer journey. Or you can start from scratch and create something completely new. But with Kodaris, getting a site up and running is easy and intuitive for any developer.