github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs/guide/installation.html (about) 1 <!DOCTYPE html> 2 <html lang="en-US"> 3 <head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width,initial-scale=1"> 6 <title>Installation | Goyave</title> 7 <meta name="generator" content="VuePress 1.5.3"> 8 <link rel="icon" type="image/png" sizes="16x16" href="/goyave/goyave_16.png"> 9 <link rel="icon" type="image/png" sizes="32x32" href="/goyave/goyave_32.png"> 10 <link rel="icon" type="image/png" sizes="64x64" href="/goyave/goyave_64.png"> 11 <link rel="icon" type="image/png" sizes="128x128" href="/goyave/goyave_128.png"> 12 <link rel="icon" type="image/png" sizes="256x256" href="/goyave/goyave_256.png"> 13 <link rel="icon" type="image/png" sizes="512x512" href="/goyave/goyave_512.png"> 14 <meta name="description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 15 <meta name="og:title" content="Installation - Goyave"> 16 <meta name="twitter:title" content="Installation - Goyave"> 17 <meta name="title" content="Installation - Goyave"> 18 <meta property="twitter:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 19 <meta property="twitter:image:src" content="https://system-glitch.github.io/goyave/goyave_banner.png"> 20 <meta property="twitter:card" content="summary_large_image"> 21 <meta property="og:type" content="website"> 22 <meta property="og:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 23 <meta property="og:image" content="https://system-glitch.github.io/goyave/goyave_banner.png"> 24 <meta property="og:site_name" content="Goyave"> 25 <link rel="preload" href="/goyave/assets/css/0.styles.589fd562.css" as="style"><link rel="preload" href="/goyave/assets/js/app.092490a7.js" as="script"><link rel="preload" href="/goyave/assets/js/4.75a9cc68.js" as="script"><link rel="preload" href="/goyave/assets/js/1.121dd9ed.js" as="script"><link rel="preload" href="/goyave/assets/js/28.41e055b7.js" as="script"><link rel="prefetch" href="/goyave/assets/js/10.2f07bbf5.js"><link rel="prefetch" href="/goyave/assets/js/11.2d66fdef.js"><link rel="prefetch" href="/goyave/assets/js/12.63171b15.js"><link rel="prefetch" href="/goyave/assets/js/13.770050f3.js"><link rel="prefetch" href="/goyave/assets/js/14.b933d8cf.js"><link rel="prefetch" href="/goyave/assets/js/15.36df2a66.js"><link rel="prefetch" href="/goyave/assets/js/16.ed66719e.js"><link rel="prefetch" href="/goyave/assets/js/17.7bef5f05.js"><link rel="prefetch" href="/goyave/assets/js/18.470b55ed.js"><link rel="prefetch" href="/goyave/assets/js/19.90e0dab8.js"><link rel="prefetch" href="/goyave/assets/js/20.3a300ca3.js"><link rel="prefetch" href="/goyave/assets/js/21.c3fd6053.js"><link rel="prefetch" href="/goyave/assets/js/22.d5569617.js"><link rel="prefetch" href="/goyave/assets/js/23.931b2034.js"><link rel="prefetch" href="/goyave/assets/js/24.1a4755e7.js"><link rel="prefetch" href="/goyave/assets/js/25.0d463913.js"><link rel="prefetch" href="/goyave/assets/js/26.3c173a7a.js"><link rel="prefetch" href="/goyave/assets/js/27.9c5b36f2.js"><link rel="prefetch" href="/goyave/assets/js/29.b87adf4a.js"><link rel="prefetch" href="/goyave/assets/js/3.ef71e77d.js"><link rel="prefetch" href="/goyave/assets/js/5.c83f1192.js"><link rel="prefetch" href="/goyave/assets/js/6.2336bf0c.js"><link rel="prefetch" href="/goyave/assets/js/7.d60e55c1.js"><link rel="prefetch" href="/goyave/assets/js/8.2ee33a42.js"><link rel="prefetch" href="/goyave/assets/js/9.8e043d60.js"> 26 <link rel="stylesheet" href="/goyave/assets/css/0.styles.589fd562.css"> 27 </head> 28 <body> 29 <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/goyave/" class="home-link router-link-active"><img src="/goyave/goyave_64.png" alt="Goyave" class="logo"> <span class="site-name can-hide">Goyave</span></a> <div class="links"><div class="user-settings"><a title="Dark theme" href="#" class="settings-button"><svg aria-hidden="true" data-prefix="fas" data-icon="cog" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="svg-inline--fa fa-cog fa-w-16 settings-icon"><path fill="currentColor" d="M8 0c-4.4 0-8 3.6-8 8s3.6 8 8 8 8-3.6 8-8-3.6-8-8-8zM8 15c-3.9 0-7-3.1-7-7 0-2.4 1.2-4.6 3.2-5.9-0.1 0.6-0.2 1.3-0.2 1.9 0 4.9 4 8.9 8.9 9-1.3 1.3-3 2-4.9 2z"></path></svg></a></div> <div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active"> 30 Guide 31 </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external"> 32 pkg.go.dev 33 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link"> 34 GitHub 35 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active"> 36 Guide 37 </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external"> 38 pkg.go.dev 39 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link"> 40 GitHub 41 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav> <ul class="sidebar-links"><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading open"><span>Guide</span> <span class="arrow down"></span></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/goyave/guide/" aria-current="page" class="sidebar-link">Introduction</a></li><li><a href="/goyave/guide/changelog.html" class="sidebar-link">Changelog</a></li><li><a href="/goyave/guide/installation.html" aria-current="page" class="active sidebar-link">Installation</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/goyave/guide/installation.html#requirements" class="sidebar-link">Requirements</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/installation.html#template-project" class="sidebar-link">Template project</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/installation.html#from-scratch" class="sidebar-link">From scratch</a></li></ul></li><li><a href="/goyave/guide/upgrade-guide.html" class="sidebar-link">Upgrade Guide</a></li><li><a href="/goyave/guide/configuration.html" class="sidebar-link">Configuration</a></li><li><a href="/goyave/guide/architecture-concepts.html" class="sidebar-link">Architecture Concepts</a></li><li><a href="/goyave/guide/deployment.html" class="sidebar-link">Deployment</a></li><li><a href="/goyave/guide/contribution-guide.html" class="sidebar-link">Contributing to Goyave</a></li></ul></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>The Basics</span> <span class="arrow right"></span></p> <!----></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>Advanced</span> <span class="arrow right"></span></p> <!----></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="installation"><a href="#installation" class="header-anchor">#</a> Installation</h1> <p>This guide will walk you through the installation process. The rest of the guide assumes you are using the template project, as it is the recommended option.</p> <h2 id="requirements"><a href="#requirements" class="header-anchor">#</a> Requirements</h2> <ul><li>Go 1.13+</li> <li>Go modules</li></ul> <h2 id="template-project"><a href="#template-project" class="header-anchor">#</a> Template project</h2> <p>You can bootstrap your project using the <strong><a href="https://github.com/System-Glitch/goyave-template" target="_blank" rel="noopener noreferrer">Goyave template project<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></strong>. This project has a complete directory structure already set up for you.</p> <h4 id="linux-macos"><a href="#linux-macos" class="header-anchor">#</a> Linux / MacOS</h4> <div class="language- extra-class"><pre class="language-text"><code>$ curl https://raw.githubusercontent.com/System-Glitch/goyave/master/install.sh | bash -s my-project 42 </code></pre></div><h4 id="windows-powershell"><a href="#windows-powershell" class="header-anchor">#</a> Windows (Powershell)</h4> <div class="language- extra-class"><pre class="language-text"><code>> & ([scriptblock]::Create((curl "https://raw.githubusercontent.com/System-Glitch/goyave/master/install.ps1").Content)) -projectName my-project 43 </code></pre></div><hr> <p>Run <code>go run my-project</code> in your project's directory to start the server, then try to request the <code>hello</code> route.</p> <div class="language- extra-class"><pre class="language-text"><code>$ curl http://localhost:8080/hello 44 Hi! 45 </code></pre></div><p>There is also an <code>echo</code> route, with basic validation of query parameters.</p> <div class="language- extra-class"><pre class="language-text"><code>$ curl http://localhost:8080/echo?text=abc%20123 46 abc 123 47 </code></pre></div><h2 id="from-scratch"><a href="#from-scratch" class="header-anchor">#</a> From scratch</h2> <div class="custom-block warning"><p class="custom-block-title">WARNING</p> <p>Installing your project from scratch is not recommended as you will likely not use the same directory structure as the template project. Respecting the standard <a href="/goyave/guide/architecture-concepts.html#directory-structure">directory structure</a> is important and helps keeping a consistent environment across the Goyave applications.</p></div> <p>If you prefer to setup your project from scratch, for example if you don't plan on using some of the framework's features or if you want to use a different directory structure, you can!</p> <p>In a terminal, run:</p> <div class="language- extra-class"><pre class="language-text"><code>$ mkdir myproject && cd myproject 48 $ go mod init my-project 49 $ go get -u github.com/System-Glitch/goyave/v2 50 </code></pre></div><p>Now that your project directory is set up and the dependencies are installed, let's start with the program entry point, <code>kernel.go</code>:</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">package</span> main 51 52 <span class="token keyword">import</span> <span class="token punctuation">(</span> 53 <span class="token string">"my-project/http/route"</span> 54 <span class="token string">"github.com/System-Glitch/goyave/v2"</span> 55 <span class="token punctuation">)</span> 56 57 <span class="token keyword">func</span> <span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> 58 <span class="token keyword">if</span> err <span class="token operator">:=</span> goyave<span class="token punctuation">.</span><span class="token function">Start</span><span class="token punctuation">(</span>route<span class="token punctuation">.</span>Register<span class="token punctuation">)</span><span class="token punctuation">;</span> err <span class="token operator">!=</span> <span class="token boolean">nil</span> <span class="token punctuation">{</span> 59 os<span class="token punctuation">.</span><span class="token function">Exit</span><span class="token punctuation">(</span>err<span class="token punctuation">.</span><span class="token punctuation">(</span><span class="token operator">*</span>goyave<span class="token punctuation">.</span>Error<span class="token punctuation">)</span><span class="token punctuation">.</span>ExitCode<span class="token punctuation">)</span> 60 <span class="token punctuation">}</span> 61 <span class="token punctuation">}</span> 62 </code></pre></div><div class="custom-block tip"><p class="custom-block-title">TIP</p> <p><code>goyave.Start()</code> is blocking. You can run it in a goroutine if you want to process other things in the background. See the <a href="/goyave/guide/advanced/multi-services.html">multi-services</a> section for more details.</p></div> <p>Now we need to create the package in which we will register our routes. Create a new package <code>http/route</code>:</p> <div class="language- extra-class"><pre class="language-text"><code>$ mkdir http 63 $ mkdir http/route 64 </code></pre></div><p>Create <code>http/route/route.go</code>:</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">package</span> routes 65 66 <span class="token keyword">import</span> <span class="token string">"github.com/System-Glitch/goyave/v2"</span> 67 68 <span class="token comment">// Register all the routes</span> 69 <span class="token keyword">func</span> <span class="token function">Register</span><span class="token punctuation">(</span>router <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Router<span class="token punctuation">)</span> <span class="token punctuation">{</span> 70 router<span class="token punctuation">.</span><span class="token function">Get</span><span class="token punctuation">(</span><span class="token string">"GET"</span><span class="token punctuation">,</span> <span class="token string">"/hello"</span><span class="token punctuation">,</span> hello<span class="token punctuation">)</span> 71 <span class="token punctuation">}</span> 72 73 <span class="token comment">// Handler function for the "/hello" route</span> 74 <span class="token keyword">func</span> <span class="token function">hello</span><span class="token punctuation">(</span>response <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Response<span class="token punctuation">,</span> request <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Request<span class="token punctuation">)</span> <span class="token punctuation">{</span> 75 response<span class="token punctuation">.</span><span class="token function">String</span><span class="token punctuation">(</span>http<span class="token punctuation">.</span>StatusOK<span class="token punctuation">,</span> <span class="token string">"Hi!"</span><span class="token punctuation">)</span> 76 <span class="token punctuation">}</span> 77 </code></pre></div><p>Here we registered a very simple route displaying "Hi!". Learn more about routing <a href="/goyave/guide/basics/routing.html">here</a>.</p> <div class="custom-block tip"><p class="custom-block-title">TIP</p> <p>Your routes definitions should be separated from the handler functions. Handlers should be defined in a <code>http/controller</code> directory.</p></div> <p>Run your server and request your route:</p> <div class="language- extra-class"><pre class="language-text"><code>$ go run my-project 78 79 # In another terminal: 80 $ curl http://localhost:8080/hello 81 Hi! 82 </code></pre></div><p>You should also create a config file for your application. Learn more <a href="/goyave/guide/configuration.html">here</a>.</p> <p>It is a good practice to ignore the actual config to prevent it being added to the version control system. Each developer may have different settings for their environment. To do so, add <code>config.json</code> to your <code>.gitignore</code>.</p></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/System-Glitch/goyave/edit/master/docs_src/src/guide/installation.md" target="_blank" rel="noopener noreferrer">Edit this page on GitHub</a> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></div> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev"> 83 ← 84 <a href="/goyave/guide/changelog.html" class="prev"> 85 Changelog 86 </a></span> <span class="next"><a href="/goyave/guide/upgrade-guide.html"> 87 Upgrade Guide 88 </a> 89 → 90 </span></p></div> </main></div><div class="global-ui"><!----></div></div> 91 <script src="/goyave/assets/js/app.092490a7.js" defer></script><script src="/goyave/assets/js/4.75a9cc68.js" defer></script><script src="/goyave/assets/js/1.121dd9ed.js" defer></script><script src="/goyave/assets/js/28.41e055b7.js" defer></script> 92 </body> 93 </html>