blob: 6eadc0476ac7bd429ec375d57bcc2e3a70f86a6e [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-112407000-2"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag() {
dataLayer.push(arguments);
}
gtag('js', new Date());
gtag('config', 'UA-112407000-2');
</script>
<!-- Google Tag Manager -->
<script>
(function (w, d, s, l, i) {
w[l] = w[l] || [];
w[l].push({
'gtm.start': new Date().getTime(),
event: 'gtm.js'
});
var f = d.getElementsByTagName(s)[0],
j = d.createElement(s),
dl = l != 'dataLayer' ? '&l=' + l : '';
j.async = true;
j.src =
'https://www.googletagmanager.com/gtm.js?id=' + i + dl;
f.parentNode.insertBefore(j, f);
})(window, document, 'script', 'dataLayer', 'GTM-KS8HHSF');
</script>
<!-- End Google Tag Manager -->
<head>
<base href="/codewind/" />
<title>Working with templates | Codewind</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Working with templates">
<meta name="keywords" content="template, project, projects, develop, development, language, languages, build, custom, layout, sample, dockerfile, docker, code, python, go, java, node, yaml..."/>
<link rel="icon" type="image/png" sizes="16x16" href="images/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="images/favicon-32x32.png">
<link href="https://fonts.googleapis.com/css?family=IBM+Plex+Sans:300,400,600&display=swap" rel="stylesheet">
<!-- Bootstrap CSS CDN -->
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css"
integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" />
<link rel="stylesheet" href="css/styles.css">
<link rel="stylesheet" href="css/docs.css">
</head>
<body data-spy="scroll" data-target="#toc">
<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-KS8HHSF"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->
<div class="main">
<!-- Bootstrap NavBar -->
<nav class="navbar navbar-expand-lg navbar-light cw-banner fixed-top">
<button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse"
data-target="#navbarNavDropdown" aria-controls="navbarNavDropdown" aria-expanded="false"
aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<a class="navbar-brand" href="">
<img src="images/header-logo.svg" class="cw-header-logo" alt="">
</a>
<div class="collapse navbar-collapse justify-content-end cw-navbar-padding" id="navbarNavDropdown">
<ul class="navbar-nav cw-navbar-nav">
<li class="nav-item cw-navbar-item cw-header-link">
<a class="nav-link cw-nav-link" href="docindex.html">Docs</a>
</li>
<!-- li class="nav-item cw-navbar-item" id="download-li">
<button onClick="window.location.href='https://microclimate.dev/download/codewind';" type="button" class="btn cw-download-button">Download</button>
<a href="https://microclimate.dev/download/codewind" class="nav-link cw-nav-link cw-download-link" href="#">Download</a>
</li> -->
<li class="nav-item cw-navbar-item" id="github-stars-button">
<!-- Place this tag where you want the button to render. -->
<a class="github-button" href="https://github.com/eclipse/codewind" data-size="large"
data-show-count="true" aria-label="Star eclipse/codewind on GitHub">Star</a>
</li>
<!-- Smaller devices menu END -->
</ul>
</div>
</nav>
<!-- NavBar END -->
<!-- Bootstrap row -->
<div class="row" id="body-row">
<!-- Sidebar -->
<div id="sidebar-container" class="bg-light">
<!-- Bootstrap List Group -->
<ul class="list-group sticky-top bg-light cw-sticky-offset">
<!-- Separator with title -->
<li class="list-group-item cw-sidebar-separator-title cw-text-gray d-flex bg-light align-items-center menu-collapsed">
<small class="badge badge-success cw-margin-auto">DOCUMENTS</small>
</li>
<!-- /END Separator -->
<!-- Hard coded TOC -->
<a href="#install_on_cloud" data-toggle="collapse" aria-expanded="false" class="bg-light list-group-item list-group-item-action flex-column align-items-start collapsed">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Installing and Using Codewind on Cloud</span>
<span class="submenu-icon ml-auto"></span>
</div>
</a>
<div id="install_on_cloud" class="cw-sidebar-div cw-sidebar-submenu collapse" style="">
<a href="installoncloud.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Installing and Using Codewind on Kubernetes</span>
</div>
</a>
<a href="supportingmultipleusers.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Support for multiple users</span>
</div>
</a>
<a href="viewkibanalogs.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Viewing logs using Kibana in IBM Cloud Private</span>
</div>
</a>
</div>
<a href="installlocally.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Installing Codewind locally</span>
</div>
</a>
<a href="#codewind_for_eclipse" data-toggle="collapse" aria-expanded="false" class="bg-light list-group-item list-group-item-action flex-column align-items-start collapsed">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Codewind for Eclipse</span>
<span class="submenu-icon ml-auto"></span>
</div>
</a>
<div id="codewind_for_eclipse" class="cw-sidebar-div cw-sidebar-submenu collapse" style="">
<a href="mdteclipseoverview.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Overview</span>
</div>
</a>
<a href="mdteclipsegettingstarted.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Installation and Getting Started</span>
</div>
</a>
<a href="mdteclipsemanagingprojects.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Managing Codewind projects</span>
</div>
</a>
<a href="mdteclipsebuildproject.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Building Codewind projects</span>
</div>
</a>
<a href="mdteclipsedebugproject.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Debugging Codewind projects</span>
</div>
</a>
<a href="mdteclipsetroubleshooting.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Troubleshooting</span>
</div>
</a>
<a href="mdteclipseuninstall.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Uninstalling</span>
</div>
</a>
</div>
<a href="#codewind_for_vscode" data-toggle="collapse" aria-expanded="false" class="bg-light list-group-item list-group-item-action flex-column align-items-start collapsed">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Codewind for VS Code</span>
<span class="submenu-icon ml-auto"></span>
</div>
</a>
<div id="codewind_for_vscode" class="cw-sidebar-div cw-sidebar-submenu collapse" style="">
<a href="mdt-vsc-overview.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Overview</span>
</div>
</a>
<a href="mdt-vsc-getting-started.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Getting started</span>
</div>
</a>
<a href="mdt-vsc-tutorial.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Tutorial</span>
</div>
</a>
<a href="mdt-vsc-commands-overview.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Commands overview</span>
</div>
</a>
<a href="mdt-vsc-commands-project.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Project commands</span>
</div>
</a>
<a href="mdt-vsc-commands-restart-and-debug.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Restart and debug commands</span>
</div>
</a>
<a href="mdt-vsc-troubleshooting.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Troubleshooting</span>
</div>
</a>
<a href="mdt-vsc-uninstall.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Uninstalling</span>
</div>
</a>
</div>
<a href="#configuring_codewind" data-toggle="collapse" aria-expanded="false" class="bg-light list-group-item list-group-item-action flex-column align-items-start collapsed">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Configuring Codewind</span>
<span class="submenu-icon ml-auto"></span>
</div>
</a>
<div id="configuring_codewind" class="cw-sidebar-div cw-sidebar-submenu collapse" style="">
<a href="usingadifferenttemplate"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Using a template repository of your own</span>
</div>
</a>
</div>
<a href="guide_performance.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Guide: Monitoring applications with the performance dashboard</span>
</div>
</a>
<a href="uninstall.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Uninstalling Codewind</span>
</div>
</a>
<a href="troubleshooting.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Troubleshooting</span>
</div>
</a>
<a href="limitations.html"
class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Limitations</span>
</div>
</a>
<!-- END hard coded TOC -->
<!-- Separator without title -->
<li class="list-group-item cw-sidebar-separator-title bg-light cw-text-gray d-flex align-items-center menu-collapsed">
<small class="badge badge-success cw-margin-auto">HELPFUL
LINKS</small>
</li>
<!-- /END Separator -->
<a href="https://projects.eclipse.org/proposals/eclipse-codewind" class="bg-light list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-start align-items-center">
<span class="menu-collapsed">Eclipse Codewind project page</span>
</div>
</a>
<!-- Logo -->
<li class="list-group-item cw-logo-separator bg-light d-flex justify-content-center">
<img src="images/header-logo.svg">
</li>
</ul>
<!-- List Group END-->
</div>
<!-- sidebar-container END -->
<!-- MAIN -->
<div id="content-container" class="py-5 px-5">
<div role="main"><h1 id="working-with-templates">Working with templates</h1>
<p>Beginning with Microclimate Version 18.09, you can add more development languages and sample projects by adding Microclimate extensions, called templates. These templates appear as new language and project types within the Microclimate user interface. You can code and develop in languages of your choice and provide sample projects that are suited to your environment.</p>
<p>Microclimate templates are stored in the <code class="highlighter-rouge">microclimate-workspace/.extensions</code> directory. Templates for Python and Go languages and for additional Java and Node.js sample projects are already included in Microclimate, and you can refer to those as examples.</p>
<p>You can create templates in one of two ways: you can create them using the template wizard, or you can create them manually. Using the wizard is easier if your project uses one of the supported languages, as shown in the following instructions.</p>
<h2 id="prerequisites">Prerequisites</h2>
<ul>
<li>You need your sample project code, either on your local disk or in a public GitHub repository.</li>
<li>The sample must include a Dockerfile, and you must be able to build and run it in Docker.</li>
</ul>
<h2 id="creating-a-template-using-the-template-wizard">Creating a template using the template wizard</h2>
<p>To create a template using the wizard:</p>
<ol>
<li>In the Microclimate header, click <strong>Templates</strong>.</li>
<li>Click <strong>Create a new template</strong>.</li>
<li>Enter a unique name and a description for the template.</li>
<li>If you have one or more compatible projects in your workspace, complete the following steps to create the template from one of those projects:
<ul>
<li>Select the <strong>Existing local project</strong> radio button.</li>
<li>Select the project from which you want to create the template.</li>
<li>Click <strong>Create</strong>.</li>
</ul>
</li>
<li>Alternatively, complete the following steps to create a template from a public Git repository:
<ul>
<li>Select the <strong>Public Git repository URL</strong> radio button.</li>
<li>Enter the repository URL, for example, <code class="highlighter-rouge">https://github.com/username/reponame</code>.</li>
<li>Change the <strong>Branch</strong> value if necessary.</li>
<li>Select the <strong>Language</strong>. Options available are Java, Node.js, Swift, Python, and Go. If your project uses a different language, <a href="#creating-a-template-manually">create the template manually</a>.</li>
<li>A <strong>Build type</strong> is selected for you based on the chosen language. Select a different build type if necessary.</li>
<li>A default <strong>Application port</strong> value is entered for you based on the chosen build type. Enter a different value if necessary.</li>
<li>Click <strong>Create</strong>.</li>
</ul>
</li>
</ol>
<h2 id="creating-a-template-manually">Creating a template manually</h2>
<p>To make your own template:</p>
<ol>
<li>
<p>Create a <code class="highlighter-rouge">microclimate.yaml</code> file to provide the specification for your sample project. See the <a href="#format-specification-of-the-microclimateyaml-file">format specification of the microclimate.yaml file</a> along with the example.</p>
</li>
<li>Your <code class="highlighter-rouge">microclimate.yaml</code> file needs to be placed in a new directory within the <code class="highlighter-rouge">microclimate-workspace/.extensions</code> directory.
<ul>
<li>The directory name must match the value you provide for the <code class="highlighter-rouge">extensionID</code> field in your <code class="highlighter-rouge">microclimate.yaml</code> file.</li>
<li>If you are providing sample project code from your local disk rather than in a GitHub repository, include the project code in the same directory. In the <code class="highlighter-rouge">microclimate.yaml</code> file, set the <code class="highlighter-rouge">localpath</code> value with a period.</li>
</ul>
</li>
<li>If you are running Microclimate in IBM Cloud Private, you can use <code class="highlighter-rouge">kubectl</code> to upload your template directory, which contains <code class="highlighter-rouge">microclimate.yaml</code>:</li>
</ol>
<p><code class="highlighter-rouge">kubectl cp &lt;your template directory&gt; &lt;namespace&gt;/&lt;ibm-microclimate pod&gt;:microclimate-workspace/&lt;icp-username&gt;/.extensions</code></p>
<p><strong>Note:</strong></p>
<ul>
<li>The <code class="highlighter-rouge">&lt;your-template-directory&gt;</code> directory must end in a forward slash (/) so that the <code class="highlighter-rouge">kubectl</code> command performs a recursive directory copy.</li>
<li>The <code class="highlighter-rouge">extensions</code> directory in the root of the file system for the <code class="highlighter-rouge">ibm-microclimate</code> pod contains only the templates that Microclimate supplies. Place your new template in the <code class="highlighter-rouge">microclimate-workspace/&lt;icp-username&gt;/.extensions</code> directory as previously described.</li>
<li>In addition to the provided language options, you can type in your own language. The manually added language will then be included as an option in the template wizard.</li>
</ul>
<ol>
<li>If you are running in a local installation, restart Microclimate. If you are running in IBM Cloud Private, restart the <code class="highlighter-rouge">ibm-microclimate</code> pod. After you restart, your template appears as a selectable project type when you create a new project.</li>
</ol>
<h2 id="format-specification-of-the-microclimateyaml-file">Format specification of the microclimate.yaml file</h2>
<p>The following code is an example <code class="highlighter-rouge">microclimate.yaml</code> file for the <a href="https://github.com/microclimate-dev2ops/microclimateGoTemplate">Go language template</a> as supplied in the <code class="highlighter-rouge">microclimate-workspace/.extensions/templateGoExample</code> directory.</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># extensionId must match the directory name, repository name, and chart/ directory</span>
<span class="na">extensionId</span><span class="pi">:</span> <span class="s">templateGoExample</span>
<span class="na">buildType</span><span class="pi">:</span> <span class="s">docker</span>
<span class="c1"># Project language to display in the Microclimate UI</span>
<span class="na">language</span><span class="pi">:</span> <span class="s">go</span>
<span class="c1"># Must be "template"</span>
<span class="na">creationType</span><span class="pi">:</span> <span class="s">template</span>
<span class="na">info</span><span class="pi">:</span>
<span class="c1"># Customize these to your liking</span>
<span class="na">provider</span><span class="pi">:</span> <span class="s">IBM</span>
<span class="na">version</span><span class="pi">:</span> <span class="s">0.0.1</span>
<span class="na">userInterface</span><span class="pi">:</span>
<span class="c1"># Template label to display in the Microclimate UI</span>
<span class="na">label</span><span class="pi">:</span> <span class="s">Go sample template</span>
<span class="c1"># Description of the template project</span>
<span class="na">description</span><span class="pi">:</span> <span class="s">Sample microservice for simple Go app</span>
<span class="na">template</span><span class="pi">:</span>
<span class="c1"># Link to the GitHub repo, if your source is in GitHub</span>
<span class="na">giturl</span><span class="pi">:</span> <span class="s">https://github.com/microclimate-dev2ops/microclimateGoTemplate</span>
<span class="c1"># Git branch to clone new projects from</span>
<span class="na">gitbranch</span><span class="pi">:</span> <span class="s">master</span>
<span class="c1"># Path to your project's root directory relative to this file</span>
<span class="c1"># Ignored if giturl and gitbranch are set above</span>
<span class="na">localpath</span><span class="pi">:</span> <span class="s">.</span>
<span class="na">application</span><span class="pi">:</span>
<span class="c1"># Application's HTTP port</span>
<span class="na">port</span><span class="pi">:</span> <span class="s">8000</span>
<span class="c1"># The application' s "root path", default is "/"</span>
<span class="c1"># Microclimate will ping this endpoint to determine when your app is running</span>
<span class="na">contextroot</span><span class="pi">:</span> <span class="s">/my-root-endpoint</span>
</code></pre></div></div>
<h2 id="limitations">Limitations</h2>
<p>Monitoring is unavailable for projects created from a template.</p>
</div>
</div>
</div>
<!-- Main Col END -->
<!-- footer row -->
<footer>
<div class="row" id="footer-div">
<div class="col-lg-3 col-md-3 footer-col text-center">
<div>
<div>
<a href="https://twitter.com/EclipseCodewind"><img src="images/twitter-logo.svg" class="cw-logo" /></a>
</div>
<div>@EclipseCodewind</div>
</div>
</div>
<div class="col-lg-3 col-md-3 footer-col text-center">
<div>
<div>
<a href="https://github.com/eclipse/codewind"><img src="images/github-logo.svg"
class="cw-logo" /></a>
</div>
<div>@Codewind</div>
</div>
</div>
<div class="col-lg-3 col-md-3 footer-col text-center">
<div>
<div>
<a href="mailto:codewind-dev@eclipse.org"><img src="images/email-icon.svg" class="cw-logo" /></a>
</div>
<div>@Codewind</div>
</div>
</div>
<div class="col-lg-3 col-md-3 footer-col text-center">
<div class="cw-logo-mm" >
<div class="cw-logo-mm" >
<a href="mailto:codewind-dev@eclipse.org"><img src="images/mattermost-logo.png" class="cw-logo-mm" /></a>
</div>
</div>
</div>
</div>
</footer>
<!-- footer row END --> <!-- Jquery -->
<script
src="https://code.jquery.com/jquery-3.4.1.min.js"
integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo="
crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js"
integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous">
</script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js"
integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous">
</script>
<!-- Font Awesome JS -->
<script defer src="https://use.fontawesome.com/releases/v5.0.13/js/solid.js"
integrity="sha384-tzzSw1/Vo+0N5UhStP3bvwWPq+uvzCMfrN1fEFe+xBmv1C/AtVX5K0uZtmcHitFZ" crossorigin="anonymous">
</script>
<script defer src="https://use.fontawesome.com/releases/v5.0.13/js/fontawesome.js"
integrity="sha384-6OIrr52G08NpOFSZdxxz1xdNSndlD4vdcf/q2myIUVO0VsqaGHJsB0RaBE01VTOY" crossorigin="anonymous">
</script>
<!-- Place this tag in your head or just before your close body tag. -->
<script async defer src="https://buttons.github.io/buttons.js"></script>
<script src="js/jquery.matchHeight-min.js"></script>
<script src="js/index.js"></script>
<script src="js/docs.js"></script>
</div>
</body>
</html>