GitLab Incubation Engineering - Jamstack, 25 Nov 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: How to Deploy Remix to the Edge — Production Ready!

Description

How to get your remix.run App to auto-deploy to Cloudflare Workers!

How to Test your App: https://docs.gitlab.com/ee/ci/testing/

Sample Project: https://gitlab.com/janis/gl-remix-cloudflare

Questions? Inaccuracies? Let me know: https://gitlab.com/janis/gl-remix-cloudflare/-/issues/new

Would you rather read this? Check my Blogpost: https://about.gitlab.com/blog/2022/11/21/deploy-remix-with-gitlab-and-cloudflare/

Chapters:
00:00 Intro
01:00 Create Remix app scaffolding
03:05 Create GitLab project
05:35 Set up Cloudflare and obtain an API token
09:23 Save API token in GitLab
11:18 Set up the deployment pipeline
18:10 Monitor your pipeline and find your Workers domain
19:20 Find your app in the Cloudflare dashboard
20:07 Watch the auto-deployment on commit
21:22 Set up a custom domain
24:50 (High level) How to add a test to the pipeline

A

Today, I'm going to show you how to create a production ready, remix deployment on.

A

Cloudflare workers using gitlab. this means we're creating a remix application.

A

That automatically deploys to cloudflare whenever you're doing a push to master.

A

Let's get started. first, we're going to create a remix application from scratch. remix provides.

A

An amazing scaffolding for that., if you have an existing remix project. Personally, I find it.

A

Easier to move the routes and components into the scaffold, rather than the other way, around.

A

All right, here we go...

A

First, we're going to execute the following: commands:.

A

`Npx create remix` and we're using the `latest` version.

A

And we're going to give this an application name., let's say.

A

Gitlab-Remix-Cloudflare. ugh,, I don't know nothing special,, but here we go.

A

Yes, that sounds good.

A

All right. we're going to select "just the basics" because we're going to configure this ourselves.

A

Now we have this whole list of options.. Here's "cloudflare workers"., make sure to.

A

Select that – this is really important. select, whether you want typescript or javascript:,.

A

That's up to you. and yes, we'd like to run `npm install` now.

A

All right, that that looks great,, let's go in there.

A

A

Here's our application.

A

Looking great! all right,, let's do an initial commit.

A

First, initialize the git repository with `git init`.

A

Then, let's add all the new files,.

A

And do the initial commit.

A

All right, now we have a local git project., let's create the remote repository.

A

So here's gitlab, open your gitlab and create "click a new project/repository".

A

Select "create blank project". right,. Here we give it the same name, `gl-remix-cloudflare`.

A

Ugh,, I could be more creative, with that. nevermind. all right,, I'm going to put this under my own user.

A

And as a deployment target select "edge computing"., this is basically for our.

A

Internal tracking, but we're going to add a bit more functionality behind this later.

A

All right, as "visibility level" choose, whichever you prefer,. This doesn't affect whether your site.

A

Is public at the end. but do remove this button? "Initialize repository with a readme"!, because we.

A

Already have an initialized repository,. If we let gitlab initialize it we'll have two.

A

Diverging histories and that's going to be a pain to resolve. all right,, let's create the project.

A

All right, here we go.

A

Now, let's take the url,.

A

And add this to the local repository.

A

A

And origin` and add the url.

A

And let's do a first push.

A

All right,, and if we reload this page, we see all the code that we just created there. perfect.

A

Right now, the next step is to actually set up your cloudflare account.

A

To allow those deployments from within gitlab. I've created a brand new cloudflare account here,.

A

It doesn't have any websites. so go ahead,, create your cloudflare account now and I'll guide. You.

A

Through the rest., this should look fairly similar if you have an existing cloudflare account., if so,.

A

Just skip the steps that don't need any setup. all right,. The first thing we need to do is to.

A

Subscribe to a workers plan, so we're going here on the left hand, side to the "workers" entry.

A

First,, we need to set up a "free custom, cloudflare workers, subdomain".

A

This is generated from the account name. yeah. That's fine for me for now,.

A

So I'm going to click this. now we need to select a plan.. I think the free plan is good for now.

A

Just check whatever your needs: are. continue with free. all right, there, you go.

A

We now have workers. we're going to create a service automatically, so skip this for now.

A

What we need to do is:, we need to obtain an api token.. You can either go here via api.

A

Tokens – or from anywhere within the site, go to "my profile". and then here: "api tokens".

A

All right, in here we are going to create a new token. click on "create token".

A

They provide us with a few templates,, which is great., and we obviously want to be able.

A

To "edit cloudflare workers",, so we're going to use this template.. The permissions are already.

A

Perfectly configured for us by that template. we now have to select the account and zone resources.

A

As "account resource" obviously select the account that you're working with.

A

And then as zone resources – the best thing to do is to be as specific as possible.. If you have.

A

A domain set up,, you can select "specific zone" and you can select that website or zone in here.

A

I haven't set up the website yet,, so I need to be a bit more general. but be aware that this api.

A

Token can now be used to deploy to any zone within the gitlab jamstack incubation, cloudflare, account,.

A

So, as you add more zones later to your account,, this token can be used again!, and this might.

A

Not actually be what you want., so I recommend being as specific as possible, in this case.

A

All right,, let's go: "continue to summary"., you can review what you've just created.

A

This should be fine for me.. If I click "create token", it will provide me with.

A

This token., you need to copy it right, away, because they won't ever show it to you. Again.

A

So to be safe,, we want to add it to the gitlab project immediately,. So it's saved. all right,.

A

Go back to gitlab., I'm still inside my project.. Now I can go to "settings > ci cd". in here. We.

A

Have the "variables"- and that is what we want to save the api token as. click on "expand".

A

We have no variables yet, obviously,, so we're going to "add a new variable".

A

We're going to put the value here and up here we're going to call this "cloudflare_api_token".

A

Make sure to use exactly this string,, because this will be used by wrangler, which is the cloudflare.

A

Cli that is going to run on the runner., so it's important that it's called exactly that.. We want.

A

To not only protect the variable because it's obviously a secret key,. We also want to mask it.

A

You can limit this to a specific environment. for now,. We only have one environment.

A

All right, click "add variable". and,. We have the variable in there!.

A

Now gitlab knows our api token, and it knows the source code.. What's missing.

A

Is a .gitlab-ci.yaml file.? This is basically an instruction to gitlab to.

A

Do something with that code whenever you're doing a push to the project.

A

So we're building this pipeline now. we're going back to the project.

A

Let's close this for now., what we're going to do is create a new file called .gitlab-ci.yml.

A

Gitlab will read this and follow the instructions provided in here.. I'm going.

A

To build a very minimal pipeline, but you can extend this indefinitely., but for now,.

A

We're going to work with a single deploy stage., this is optional,, but I think it's it's important.

A

To start that from the beginning: we're going to start with stages., this is basically a list of.

A

Stages that your pipeline is going through., we have only have a single stage for now,.

A

And it's called "deploy". and here's the job description: we're going to call it deploy-worker.

A

This is basically the job that is being executed, with its name, and here's. The instruction: first,.

A

We're going to specify an image that is going to be used.. Add some docker image., because we're.

A

Using npm and npx for that,, I I'd recommend just using the node long-term support. Image.

A

All right, here we go. we're going to assign this job to a stage.

A

And this is basically the same name as defined here,, so it needs to be one of this list.

A

We're now using environment.

A

I'm calling this production.

A

And this is the environment that I referred to, earlier, in the variable screen,.

A

Right?, you can limit a certain variable to be available only in a specific environment.

A

All right, so we're going to run a little before_script:.

A

This is basically the first script that is being executed, before the main script. Runs,.

A

And this is a list of shell commands.: let's use `npm ci`.. This is basically an npm install that.

A

Makes sure that it uses the package-lock file, rather than the package.json., so you.

A

Can be sure that it uses those dependencies that you've actually developed with locally.

A

You could still use `npm install` if you don't care about that.

A

All right, now, let's go for the main script.

A

Here goes the script, another list of shell commands. in here we can just run `npm.

A

Run deploy`, so this is going to run this command from the package.json,.

A

This came with the scaffolding from remix.. It's going to execute.

A

A command called `wrangler publish`. wrangler is the cloudflare cli tool,.

A

That uses the environment variables to detect what account you're using,.

A

And uses this wrangler.toml to identify what it's going to do,.

A

And then publishes this to cloudflare using the cloudflare api., so we can abstract this.

A

In here, by just using `npm, run deploy`. then,. Whenever you make a change to this command,.

A

It will pick that up immediately. again,, you could run `npx wrangler publish` as well,.

A

That would be allowed, too. right. next step,. I want to add some rules.

A

This .gitlab-ci.yaml is evaluated every single time. You push to any branch whatsoever in your.

A

Project., we need to make sure that it only runs this deploy job whenever you're pushing to main.

A

Or master., so we want to put a safeguard in here., say if $ci_commit_ref_name —.

A

So this is a variable that contains the name of the branch that you just committed. To.

A

And we're going to compare this with $ci_default_branch.

A

And this is basically the name of your default branch of the project,.

A

Be it `main` or `master` or whatever you're using., so this rule makes sure we're going to execute.

A

This worker job only after any push to main. all right,. This is basically all there is to it.

A

Now we have the .gitlab-ci.yaml file and we can just add that to the commit.

A

Let me clear this. and let's go. git add...

A

And add a commit message.

A

And now let's do a git push.

A

This will immediately execute this pipeline,. So let's go back to gitlab.

A

And go to "ci/cd".

A

And, as you can see here, this pipeline is now running.

A

In here you see the name of the stage and the name of the job that is running.. Let's watch this.

A

Now this is done. in here you actually see the url that cloudflare has assigned to your worker for.

A

Now., this consists of "workers.dev", your account name as the subdomain, and your application name.

A

As the sub-sub-domain., you can actually change this application name inside the wrangler.toml.

A

And this is the url – when you click on it initially,. It may not already be there yet,.

A

Because on the initial deployment, cloudflare has to set up this.

A

Url., you can go to the cloudflare dashboard to monitor:, go to workers,.

A

Now we have this new worker service here., so we can click on this and see an overview.

A

If we go to a route, we should be able to see – here,, it's still initializing., so we have to.

A

Wait until this is done. after a while this one switches to "enabled",, which means we can now.

A

Finally, click this link. and here's our remix app!. Isn't that amazing? we did that! (it's a [, __ ].

A

App, but there it is!, you get the general gist, right?) okay,. Now the amazing thing is:. This is.

A

Set up to auto, deploy from any pushes to master – or main, sorry.. Let me demonstrate that really.

A

Quickly! I'm going to go into the application, routes, index.. Let me just switch up something...

A

Right there., let me commit that. thank you,, all right. and if I go into ci/cd,.

A

Let's see – the pipeline is running again.. We can wait for that.

A

We don't *have* to go in there,, but I'd like to monitor what's happening., but you can just ignore.

A

This and just be confident that the deployment works on its own. okay,. Let's wait, again...

A

All right, now it's done and we can reload this page.

A

All right!, where to go from here? the next step is – I'm going to demonstrate you how to.

A

Create a custom domain with that.: this is assuming that you already registered a domain.

A

Somewhere else,, I'm not going to demonstrate you how to do that.. Let's say we already have one,.

A

I can click on "add site"., I'm gonna use a random one,.

A

Cloudflare is going to complain about it., but let's say I have my-remix-site.com.

A

Yeah,, I don't know.

A

Let's say this is my domain.: I can click "add site".

A

I will have to select a plan, and I'm going to be happy with "free" for now.

A

Obviously, the dns records are going to fail. Now.

A

I'm going to to skip this step,, you obviously would want to add a record or do the same thing at your dns registrar.

A

Yeah, yeah,, of course, I'm going to accept that, all right., but I have set up the domain now,.

A

As you can see, now, this is the main dashboard and I now have this my-remix-site.com entry in here.

A

Now we have a site-specific dashboard.. The one thing that's still missing is setting up workers.

A

Routes., this is inside the sites dashboard in the sidebar. choose "workers", "routes".

A

We currently don't have any routes configured,, so we have to do that.

A

I can now click "add route".. This is basically a pattern., so I can redirect. any request with.

A

That route is going to be redirected to my worker.. I want `my-remix-site.com.

A

/*` – this means all the requests to to that. Url are going to be redirected.

A

To this service. and I'm going to select the gl-remix-cloudflare worker that we set up earlier.

A

We could, at this stage, also redirect all subdomain requests to this,, which is important.

A

If maybe you want the `www` domain there as well., but for now I just want the top level domain to be.

A

Redirected to that route. I want the environment "production", because I only have that right. Now.

A

And I can click "save", and that means that now I could use this domain to open my remix.

A

Application. again, caveat:- I haven't actually set up this domain., but this is how you would do that.

A

All right, one more thing to get your remix application production ready.

A

And this is more to do with the gitlab pipeline.. Let me open the project back.

A

Up., this .gitlab-ci.yaml file is obviously a pipeline description,, and this is a pretty.

A

Minimal pipeline that just does a deployment., so we could add, for example, a test stage in here.

A

And in that test stage we could have a test job.

A

And it would probably look pretty much pretty similar: image:node.

A

Long-Term-Support, stage:test.

A

Any environment,, so I'm not going to specify that. again,.

A

In the test, we need to have the before_script.

A

And then, as the script, I'm going to run.

A

`Npm run test`. that is, obviously,. If you have a test script in here., I'm going to post a link.

A

To the documentation, because I can't possibly give you all the different ways of how to set.

A

Up a beautiful pipeline and I think, there's people at gitlab that can talk a lot better than I about.

A

This., but this is how you would superpower your remix application deployment, and how to get it.

A

Production ready, really,, really fast.. For now, I'm gonna stop here,. I really hope you enjoyed this.

A

Little tutorial!, if you have any questions, please reach out to me. I'm gonna put my contact details.

A

Below. and I'm here for any help,, I'm also in the remix discord,. So whenever you mention "gitlab".

A

It's probably pinging me,, so let me know if you have any questions, and I'm here to help.

A

I think this is a really great setup. I hope to see a lot of deployments like this on gitlab!.