Get started

Install

To install ArcGIS Web AppBuilder, complete the following steps:

1. Download the ArcGIS Web AppBuilder 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 ArcGIS Web AppBuilder 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.

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 https://[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, https://[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 https://[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 https.

     2. Start Web AppBuilder in the browser with the port number specified above at https://[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 Developer 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.
   1. On the My Content tab of the content page, click New item or Add Item, and choose to add an application.
   2. Complete the web form by specifying the following parameters:
      • Type—Select Web Mapping.
      • Purpose—If necessary, select Ready to Use.
      • API—If necessary, select JavaScript.
      • URL—Enter https://[yourmachinename]:3344/webappbuilder.

        Tip:

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

      • Title—Enter something that makes sense to you, such as ArcGIS Web AppBuilder.
      • Categories—If applicable, assign a category that will be used to organize and group your app. This gives your item a focused search when users are searching for items.
      • Tags—Optionally enter something that is easy to search, such as Web AppBuilder.
   3. Click Save or Add Item.
3. On the item details page, click the Settings tab. Scroll down to the App Registration section and click Register.
4. In the Register window, for App Type, keep the default value. For Redirect URI, enter https://[yourmachinename] and click Add.

   Tip:

   If Web AppBuilder is started with the machine name along with the domain name, enter 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.
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.