2.1 A student's guide to Firebase V9 - Project configuration

Introduction

The first post in this series, (Introducing Google's Firebase), showed in outline how a smart enthusiast, armed with nothing more than a knowledge of basic html and javascript could achieve very useful results in IT through the use of Google's Firebase Cloud platform. The result of their efforts would be a "webapp", hosted for free on the web by Google, accessed via a browser on any type of web-enabled device and capable of performing really serious tasks.

If you've been following my suggestions thus far, you'll have got a basic grip of coding programming instructions using the html and javascript language. You'll also have got yourself familiar with the idea of using an IDE such as VSCode to create and edit the source files for these instructions. Very good. The next step is to consider how you might actually go about using Google Cloud services to build a webapp - executable code and shared data "hosted" (ie stored) remotely on the web and available to anyone who might wish to access it via the internet.

In simple terms, what we're about here is arranging a mechanism to transfer our local project (ie, the collection of files that we've developed on our own hardware) up into the Cloud. Google refers to this process as "deployment".

In the diagram above, "Assets" refers to the collection of resources - icon files and graphic images etc - that you reference in your code and which therefore need to accompany your webapp into the cloud. Once you get your head round the concept, the process is actually pretty routine. With everything correctly configured, you can "redeploy" changes to your application with just a couple of keystrokes. But getting your head round the multitudinous components of Google Cloud services and setting them up correctly in the first place represents quite a steep learning curve. So buckle up for a bumpy initial ride. Don't worry - it'll be worth it!

If you've never used Google's services before you'll need to negotiate four separate steps:

1. Obtain a Google gmail account
2. Create a Firebase project under this account
3. Use the "Hosting tool" to register the webapp
4. Set up your local "Deployment" environment

Step 1 - Obtain a Google gmail account

You may have a gmail account already of course. If not, follow instructions at Create a Google Account to get one.

Step 2- Create a Firebase project and reserve your webapp's URL

Launch the Google Firebase console to create your Firebase Project. Click "add project" and note the advice about Google Cloud projects in general. Google Firebase projects are just a special case of a wider class of Google projects that can be viewed at the parent Google Cloud console. We can safely ignore the cloud console for now.

The next stage is to specify a project-id for the webapp - the "root" of its url (which will actually take the form 'project-id'.web.app). It's important that you get this right as, once the project-id is registered, you can't change it. Worse, once you've "claimed" a project id, nobody else can claim it either, even though you may subsequently have deleted it!

Note. Firebase actually gives you two names for your webapp - in addition to the 'project-id'.web.app version shown above you can also access your site as 'project-id'.firebaseapp.com.

Matters are complicated by Google first asking you to supply a "Project name" for the parent project and then proposing a Project-id based on this (ie, rather than the other way around). It's odd that they should do this as the Project Name is the least of your worries (it serves only to distinguish projects within your Google account and can be edited at any time). But this is how things work at November 2021. As an example, you might enter "My New Webapp" as the project name, for which Google would then propose a Project-id such as my-new-webapp-39959. However, you're then free to edit the proposed project Id and massage it into a more acceptable form - subject to the constraint, as mentioned above, that nobody else has used your proposed id. The Project-id must also be at least six characters long and can only use numbers, lower-case characters and hyphens.

In the examples that follow I've used a project I registered with a Project-id of "fir-expts-app" for a project named "Firebase Experiments"

Once you've finished wrestling with Google over your Project-id, click "Continue" to reveal a page that talks about "Google analytics". This is something you can safely ignore at this stage (it's only generally relevant to the investigation of performance issues on live apps), so decline this and continue.

The lights now dim a little as Google registers your project. Then, after you've clicked a final "continue", you'll find yourself in the main Firebase Console window for your project. You'll spend quite a lot of time on this page and its sub-pages during the development process, so best get used to it. Here's a screenshot

The left-hand side of the screen is devoted to tool tabs and I've increased the screen character size a little so we can concentrate on the Project Overview gearwheel and the "Build" tool stack below this As you may imagine the full tool stack is a lot more extensive but, for the present, this is all we need.

Note also that the Test Firebase Project is automatically registered at this stage for the "Spark plan". I've said previously that using Google's Cloud Services is free, and the "Spark plan" does indeed give you access to most services free of charge. However, once your usage strays outside certain (extremely generous) limits you will be asked to register for paid plans. See Firebase Pricing Plans for details.

Firebase, as you'll slowly come to appreciate, is made up of a number of distinct "modules", each addressing different aspects of the system. Not all of these are necessarily relevant to any given application and in this post I'm just going to concentrate on the following three:

1. Authentication - specification of the way that users identify themselves to the application, and management of individual registrations
2. Firestore Database - the specification and management of a "NoSQL" database for the application and the specification of security rules to protect it.e
3. Hosting - registration of the type of application that's being developed (a webapp in this case).

Step 3 - use the "Hosting tool" to register the webapp

Click the "Hosting" tab in the Firebase console to reveal the following window:

Click the </> icon to tell Firebase you're developing a webapp, supply a nickname in the screen that follows (I suggest you just use your Project-id to avoid further confusion), ignore the offer to "set up Firebase Hosting for this app" and then click "Register" to complete the Firebase side of the hosting setup.

You might as well close down the Firebase console now. Though the Hosting window still has plenty of advice about what to do next, in practice you're on your own here. Let's just pick our way through this gently and thoughtfully.

Step 4- set up your local "Deployment" environment

The aim of this step is to use Google utilities to create files and folders, both in your "project" (ie the folder of files that you're going to build up in your PC or Mac to hold the code for your webapp) and elsewhere. These will ultimately allow you to run the "deployment process. This is a big step, so best take a deep breath now.

Let's imagine that you've already created your project folder (say firexptsapp) and added this to the VSCode workspace. Once you've completed Step 4 you'll be able to start a "Terminal" session (I'll explain just what ths is in a moment) in VSCode that targets the firexptsapp project and enables you to issue a one-line command firebase deploy command to copy your webapp onto the Google servers.

Once you've done this, anybody, anywhere in the world will be able to run your webapp by typing its name into their web browser. Wow! But getting to this point will require quite a bit of effort.

If your experience of IT to date has been entirely through the use of "click and point" Windows (Microsoft) and iOS (Mac)screens, Step 4 with its reliance on "Terminal" sessions is likely to represent a big challenge.

The word "terminal" in this context takes us back to the early days of computing, long before the appearance of the "graphical user interfaces" that we use today to drive IT applications. Developers then used "terminal" devices such as teletypes or "vdu" visual display units and gave their operating system instructions by typing them in as in "commands" rather than clicking button prompts. These "command shell" interfaces have great advantages for system programmers as they're easy to set up and highly flexible. The Google developers have chosen to use this approach for configuring and applying Firebase project deployment. While this may seem a retrograde step, please accept my assurance that once you become familiar with the concept, the arrangement is perfectly practical and, in any case, will add another useful building block to your growing range of development skills. Command shell interfaces are currently widely used in this sort of situation

If you're using an IDE like VSCode, you'll find that it provides a facility to start a terminal session focussed on your firexptsapp project. Once you've opened your terminal window, it displays a "command prompt" confirming the current directory and waits for you to type in a command.

The command we want to perform is the firebase deploy command I introduced above. But if you tried this now you'd just get an error because, at this stage, the system doesn't know what firebase means. The first thing we need to do, therefore, is add the Google files and folders required to supply this meaning. To achieve this we'll use a npm install -g firebase-toolscommand in the terminal session:

But now we hit another snag as it's likely that the system doesn't know what npm is either - possibly you yourself are in the same position. And then because npm is a Javascript program, we need an application called Node.js to run it. So you'll have to install this too.

Right, you are probably now wishing that you'd never heard of Firebase, but stick with me, because this is as deep as we're going to dive and all of this is yet more useful experience.

Let's start with an explanation of what Node.js and npm are. The Google software that you need to run in order to configure your firexptsapp folder is distributed from central web-based libraries in the form of "packages" - carefully structured files of code to perform particular tasks. Because many of the tasks that your package needs to perform are tasks that are common to other similar packages, a package will likely call upon other packages to perform these rather then coding them afresh. These packages in turn may call upon other packages, and so on. At the end of the day, therefore, in order for your package to run in your terminal session, all the necessary bit must be hauled down from the central repository and assembled in folders on your local computer. For this, you need a "package manager". npm is the package manager we're going to use in this particular exercise.

A new problem now arises. As already mentioned, npm is written in javascript and so needs an environment in which it can run. The only such environment you've encountered thus far is a computer browser and this is not something that's considered appropriate for this particular application. Node.js is the environment of choice for systems developers in these circumstances. This can be installed from the web, just like you might install any other Windows or OS app. Once it's installed, you can then start it up in a terminal session and type in javascript commands. In this sense, it's just like the facility you saw in the browser system tools console that you were introduced to in the "debugging" section of the original "Path" post.

So, all that said , here we go with Step 4 (see Firebase CLI reference for further background, if you feel you need it):

4.1 Install Node and npm - see OpenJs Home Page for instructions (I think that it's generally best if I refer you to source documents for procedures like this so you can be sure you're always looking at the latest information). Conveniently, you'll find that currently you don't have to install npm itself explicitly - installing Node.js automatically installs npm as well.

4.2 Install firebase-tools - we're now in a position to install the Firebase CLI. So, open a terminal session for your project and type in the command first described above

npm install -g firebase-tools

If this is your first time with npm, you may find this particular ride a somewhat alarming experience. Unpacking a complex package like the CLI is an extremely complex process because npm is at every stage faced with multiple versions of sub-packages and has to deal with possible incompatibilities. The process may take some time and may, indeed, occasionally appear to have died! But stick with it until it redisplays the command prompt and don't be too alarmed by any warnings that may be displayed. As long as you're using the most up to date version of npm (see Try the latest version of npm if you're having problems), everything should be fine.

4.3 Log into Firebase using your Google account

Type the following command into the terminal

firebase login

Unless you're already logged in, this should open up a browser window requesting your Google account details. Type these in to proceed.

4.4 Create a firebase.json file and deploy your project

Your almost ready to run a firebase deploy command but first you need to create the firebase.json file that will tell this what it should do.

The firebase.json file lives in the project root and you could create it yourself quite easily. But it makes more sense to use the firebase init CLI tool.

For our immediate purposes, all we need to do to run this is enter the following command into the terminal window (still focussed on the project root)

firebase init hosting

Once you've confirmed that "yes", you do want to proceed (by typing Y and hitting the return key), the CLI will ask you for the name of the Firebase project to be associated with this local installation. Select the "use an existing project" option to reveal a table containing the name of your Firebase project ("Firebase Experiments" in this example). Select this using the arrow key and proceed to "Hosting setup" wherein the CLI will ask you yet more questions.

Press the return key to select "public" as your public directory (more on this in a moment) and "Y" to have "hosting" configured as a "single-page app" (more, ditto) and, finally, "N" in response to "Set up automatic builds and deploys with Github".

And now - cue fanfare of trumpets - the CLI should respond by saying "Firebase initialization complete!" and returning you to the command prompt line.

You might find it instructive to have a look at the firebase.json that should now have appeared in your project root. It should look something like the following:

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

The main thing to note here is that this will tell firebase deploy to look in your public folder for the source that its to upload to the Google cloud. Just in case you're curious, the rewrites section is a consequence of you opting to build a "single-page" app. What it's saying is that a url of the form fir-expts-app.web.app/some-invalid-url would be redirected to your index.html file. When, later in this series, we look at the need to deploy more than just application source files, you'll see that we use other variants of the firebase init command and that the contents of firebase.json will get a lot more interesting.

But this is enough for now because, believe it or not, you're now ready to perform your first "deploy".

I know you haven't actually written a line of code yet, but firebase init hosting will have created a demo index.html script in your project and so you can trial the deployment procedure right now. All you have to do is enter the following command:

firebase deploy

in response to which, you should see the CLI return something like the following:

PS C:\Users\webappdeveloper\firexptsapp> firebase deploy

> === Deploying to 'fir-expts-app'...

i  deploying hosting
i  hosting[fir-expts-app]: beginning deploy...
i  hosting[fir-expts-app]: found 1 files in public
+  hosting[fir-expts-app]: file upload complete
i  hosting[fir-expts-app]: finalizing version...
+  hosting[fir-expts-app]: version finalized
i  hosting[fir-expts-app]: releasing new version...
+  hosting[fir-expts-app]: release complete

+  Deploy complete!

Project Console: https://console.firebase.google.com/project/fir-expts-app/overview
Hosting URL: https://fir-expts-app.web.app
PS C:\Users\webappdeveloper\fir-expts-app>

That line Hosting URL: https://fir-expts-app.web.app should look familiar - yes it's the name of the webapp. Copy this to the clipboard and paste it into your favourite browser. When you press the return key, the browser should display something like the following:

Great - you've just deployed an app into the Google cloud. Let's look into your project folder to see where this code has come from. The structure of your folder should look like the following:

fir-expts-app
    public
        index.html
    .firebasesrc
    .gitignore
    firebase.json  

The project directory was empty to start with so all of these files must have been created by firebase init. What are they all?

Well, the .firebasesrc file is mainly just there to mark the directory as a firebase project, and the .gitignore is a file in which we can specify any files that we would not wish to see copied to our git project (a version-control/open-source-sharing system) if we were using one - which, in this case, we're not at present.

The firebase.json file we've already covered so, for the present, the main thing you'll be interested in is the auto-generated index.html file in the public folder. This is what you've just deployed to generate the screen you saw above.

And this is where you'll write your own code. Check out the next post in this series to find out how.

Postscript

I think it's worth commenting that, after you've been working with Firebase for a while, you'll find that you have accumulated quite a collection of Firebase projects, each liked to its own individual VSCode project. It took me a while to realise that several VSCode projects can actually share a common Firebase project once firebase init hosting has been used to link them up. Each of these has access to the common project's Firebase storage and Firestore collections.

Of course, at any given moment, only one of these VSCode projects can actually be the deployed version of the common Firebase project, but this arrangement can open up many useful opportunities for the developer.