Get started

Install

To install Web AppBuilder for ArcGIS, complete the following steps:

  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 Web AppBuilder for ArcGIS download package contains the Windows version of Node.js.
    • If you are on a Windows platform, proceed to 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 later.
  3. Note:

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

Start Web AppBuilder

To start Web AppBuilder, complete the following steps:

  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 the domain name along with the machine name to get started, for example, http://[yourmachinename].[yourdomain]:3344/webappbuilder.

    • On platforms other than Windows, 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 browser, or a different one, 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

To use Web AppBuilder, you must have an ArcGIS organizational account or an ArcGIS for Developers account.

  1. Specify the URL for the ArcGIS organizational account that you want Web AppBuilder to access.
    Subscription:

    If you don't have an ArcGIS account, sign up for an ArcGIS free trial or the ArcGIS Developer Program.

  2. Click Continue.
    • If the portal you specified above uses web-tier authentication, skip the next section. After login, you can build your first app.
    • If you're using ArcGIS Online or ArcGIS Enterprise 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

If 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.

Complete the following steps to retrieve an app ID:

  1. Log in to the portal you specified above.
  2. Add Web AppBuilder as an item.
    • With ArcGIS Online, ArcGIS Enterprise, or Portal for ArcGIS 10.3.1 or later, do the following:
      1. Go to the My Content tab of the content page, 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 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 Web AppBuilder.
        Application dialog box
      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 drop-down box, choose An application as shown below. Change the following items. Keep the default values for the rest of the items.
        • URL—Enter http://[yourmachinename]:3344/webappbuilder.
          Tip:

          If 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 Web AppBuilder.
        Add Item dialog box
      3. Click Add Item.
  3. On the item details page, do the following:
    • For an ArcGIS Online organizational 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 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 for more information. If you have problems logging in, 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 the OpenSSL FAQ page for more information.

Build your first app

You are now ready to build your first app.