Get started

Install

  1. Download the Web AppBuilder for ArcGIS (Developer Edition) ZIP file to your local drive and unzip it.
  2. Because Web AppBuilder runs on top of Node.js, you must have Node.js installed on your computer. The download package contains the Windows version of Node.js.
    • If you are on a Windows platform, you can follow the steps in the next section to start Web AppBuilder.
    • If you are on a platform other than Windows, such as Mac or Linux, you need to install Node.js independently on your platform first. If you already have Node.js installed, make sure its version is 4.2 or higher.
  3. Note:

    The minimum version of Node.js supported by Web AppBuilder is 4.2 and higher. The 4.2 version is the first Node.js LTS (long term support) version.

Start Web AppBuilder

  1. Start Web AppBuilder based on your platform.
    • On Windows, double-click the startup.bat file in the unzipped folder. The batch file starts the Node.js server in the Command Prompt window and Web AppBuilder in your default browser with http://[yourmachinename]:3344/webappbuilder. If the browser is closed, you can reopen Web AppBuilder in the same—or a different—browser as long as Node.js is running in the Command Prompt window.
      Tip:

      If the machine is in domain, it is sometimes required to include domain name along with the machine name to get started, like http://[yourmachinename].[yourdomain]:3344/webappbuilder.

    • On other platforms, open the Command Prompt window, cd to the /server directory of the Web AppBuilder installation, and type node server.js. Once Node.js runs, start Web AppBuilder in the browser with http://[yourmachinename]:3344/webappbuilder. If the browser is closed, you can reopen Web AppBuilder in the same—or a different—browser as long as Node.js is running in the Command Prompt window.
  2. Web AppBuilder runs on top of Node.js with the default port of 3344. To run Web AppBuilder with additional parameters, different ports, or as a Windows service, complete the following steps. Otherwise, see the Specify your portal URL section.
    • Run with additional parameters and different ports.
      1. Open a command window and browse to the /server directory of the Web AppBuilder installation.
        • On 64-bit Windows, type node_x64.exe server.js [-port=value] [-proxy=value].
        • On 32-bit Windows, type node_x32.exe server.js [-port=value] [-proxy=value].
        • On other platforms, type node server.js [-port=value] [-proxy=value].
        Note:

        -port specifies the port you want Node.js to run on, and -proxy specifies the proxy URL if needed. Make sure your proxy URL starts with http or https.

      2. Start Web AppBuilder in the browser with the port number specified above at http://[yourmachinename]:[yourport]/webappbuilder.
        Tip:

        If you have problems starting Web AppBuilder, see FAQs for more information.

    • Run as a Windows service.

Specify your portal URL

  1. Specify the URL for the ArcGIS Online organization or Portal for ArcGIS account that you want Web AppBuilder to access. To use Web AppBuilder, you must have an ArcGIS Online organization account, a Portal for ArcGIS account, or an ArcGIS for Developers account.
  2. Click Continue.
    • If the portal you specified above uses web-tier authentication, skip the next section. After log in, you can build your first app.
    • If you're using ArcGIS Online organization or portal with OAuth2 authentication, follow the steps in the next section to provide an App ID for Web AppBuilder.

Provide an app ID for Web AppBuilder

Since this is the first time you've used Web AppBuilder with the portal specified above, you may be asked to provide an app ID for Web AppBuilder to support OAuth2 authentication. For a specified portal, this process is required once. When you subsequently start Web AppBuilder, you can log in to the portal directly.

Do the following to retrieve an app ID:

  1. Log in to the portal you specified above.
  2. Add Web AppBuilder as an item.
    • For an ArcGIS Online organization or a Portal for ArcGIS 10.3.1 and later account, do the following:
      1. Go to My Content. click Add Item, and choose An Application.
      2. In the Application dialog box, change the following items. Keep the default values for the rest of the items.
        • URL—Enter http://[yourmachinename]:3344/webappbuilder.
          Tip:

          If the Web AppBuilder is started with the machine name along with the domain name, enter http://[yourmachinename].[yourdomain]:3344/webappbuilder.

        • Title—Enter something that makes sense to you, such as Web AppBuilder for ArcGIS.
        • Tags—Enter something that is easy to search, such as Registered Web AppBuilder.
        Add Item dialog box for ArcGIS Online and Portal for ArcGIS 10.3.1 and later
      3. Click Add Item.
    • For Portal for ArcGIS 10.3, do the following:
      1. Go to My Content and click + Add Item.
      2. In the Add Item dialog box, in The item is text box, choose An application as shown below. Change the following items. Keep default values for the rest of the items.
        • URL—Enter http://[yourmachinename]:3344/webappbuilder.
          Tip:

          If the Web AppBuilder is started with the machine name along with the domain name, enter http://[yourmachinename].[yourdomain]:3344/webappbuilder.

        • Title—Enter something that makes sense to you, such us Web AppBuilder for ArcGIS.
        • Tags—Enter something that is easy to search, such as Registered Web AppBuilder.
        Add Item dialog box for Portal for ArcGIS 10.3
      3. Click Add Item.
  3. On the item details page, do the following:
    • For an ArcGIS Online organization or an ArcGIS for Developers account, click the Settings tab. Scroll down to the App Registration section and click Register.
    • For Portal for ArcGIS, click Register in the App Registration section.
  4. On the Register dialog box as shown below, for App Type, keep the default value. For Redirect URI, enter http://[yourmachinename] or https://[yourmachinename] and click Add. Be aware that URIs with HTTP and HTTPS protocols are distinguished as two different URIs. It is strongly recommended adding both of them to the URI list to avoid potential redirect issues.
    Register dialog box
    Tip:

    If the Web AppBuilder is started with the machine name along with the domain name, enter http://[yourmachinename].[yourdomain] or https://[yourmachinename].[yourdomain].

  5. Click Register.
  6. On the item details page, copy the app ID under App Registration.
  7. In the browser, paste the app ID into the text box of Web AppBuilder, and click Continue.

    If you get an Error 400 with Invalid redirect_url, complete the following steps:

    1. Go to the /server directory of the Web AppBuilder installation, and delete the signininfo.json file.
    2. Review step 4. Update the existing app ID with the correct redirect URIs. You can also create a new app ID from scratch.
    3. Refresh the browser running Web AppBuilder.
    4. Provide your app ID again, and click Continue.

  8. Provide your credentials if you're not already logged in, or click Approve on the Request for Permission dialog box.
  9. An app ID is required by OAuth 2 authentication. See Authentication and OAuth2. If you have problems logging on, see FAQs and Add apps and register your app.
    Tip:

    Web AppBuilder uses a self-signed certificate in Node.js to support HTTPS by default. If you want to start Web AppBuilder in your full HTTPS site, you can use your own certificate. To do so, replace two files in the server directory: cakey.pem and cacert.pem. See this blog for details. Also visit nodejs and https://www.openssl.org/docs/faq.html#USER3 website for more information.

Build your first app

You are now ready to build your first app.