DEV Community

How to fake AWS locally with LocalStack

Joseph Thomas on March 11, 2019

If you're anything like me, you prefer to avoid logging into the AWS console as much as possible. Did you set up your IAM root user with 2FA and co...

Read full post

Carlo Gino Catapang • Aug 12 '20

Great article, kudos to you mate. 1 issue in my case, image localstack/localstack did not have the web ui localhost:8080 during my testing. I needed to use localstack/localstack-full to enable web ui.

Marc Muller • Sep 12 '19

Many thanks for the article!

I had troubles: my app is running in a docker container and I was getting connection refused (ECONNREFUSED) when trying to reach the localstack container. After trying a lot of config variants, I ended up with this:

AWS.config.update({
    accessKeyId: '123',
    secretAccessKey: 'xyz',
    endpoint: 'host.docker.internal:4572',
    s3ForcePathStyle: true
});

Both endpoint and s3ForcePathStyle are important here. s3ForcePathStyle tells the sdk to use url of the from hostname/bucket instead of bucket.hostname.

Besides being the only configuration working for me, with this, I don't need to prepend bucketName in my params:

Key: `${bucketName}/${name}`

becomes

Key: `${name}`

This was not the intended effect (I was just trying to get a working connection between my app and the s3 container). Hope this can help someone else.

Thanks again for your article!

Joseph Thomas • Sep 12 '19 • Edited

Hi Marc, thanks for pointing this out! I've updated the article and the demo repo with these changes.

It's still working for me when I use http://localhost:4572 as the endpoint, so I left that as-is.

Marc Muller • Sep 13 '19

Awesome!

With a few more experimentation, I'm now using both variants:

host.docker.internal when my app is dockerized (which happens when I'm TDD'ing, most of the time)
localhostwhen my app is not dockerized (happening on my CI testing job)

Marcos Dias • Sep 25

I also got the ECONNREFUSED error, but while running my application outside a container. Turned out that using 127.0.0.1 instead of localhost in the endpoint param was the solution. I'm on MacOS.

Javier Marquez • Aug 10 '19 • Edited

Thanks Joseph for this article, it really got me started with localstack.

It seems that the number of ports that localstack uses has grown since this article was written, and I found myself if problems because localhost:4592 wasn't forwarded in the example (STS in localstack's aws).

It took me a while to realize it was that! Could you update the example to forward all the new ports? Something like:

ports:
      - '4563-4599:4563-4599'

Cheers!

Joseph Thomas • Aug 10 '19

Just updated, thanks for letting me know!

qiang • Aug 7 '19

Nice solution. However I met a problem , localhost:4572/ can show the bucket, but nothing on localhost:8055/

bcaf1ffd86f41161ca5fb16fd081034f
webfile

demo-bucket
2006-02-03T16:45:09.000Z

another problem is , when test the test-upload.js
it report below error :
"UnknownEndpoint: Inaccessible host: demo-bucket.localhost'. This service may not be available in theus-east-1' region."

I'm new novice of the S3 and docker, Could you point out how to set region for localhost s3 service.

Michael Pablo Gomes da Silva • Sep 15 '20

Hi there!
I know that is 2020, but better later than never. So my solution for this problem was:
.env
AWS_ACCESS_KEY_ID='default'
AWS_SECRET_KEY='default'
AWS_BUCKET_NAME='demo-bucket'
AWS_REGION='us-west-2'
AWS_S3_ENDPOINT='localhost:4572'

aws.js
const AWS = require('aws-sdk')
require('dotenv').config()

const credentials = {
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
secretAccessKey: process.env.AWS_SECRET_KEY,
}

const useLocal = process.env.NODE_ENV !== 'production'

const bucketName = process.env.AWS_BUCKET_NAME

const s3client = new AWS.S3({
credentials,
endpoint: process.env.AWS_S3_ENDPOINT,
region: process.env.AWS_REGION,
s3ForcePathStyle: true
/**
* When working locally, we'll use the Localstack endpoints. This is the one for S3.
* A full list of endpoints for each service can be found in the Localstack docs.
*/
})

const uploadFile = async (data, name) =>
new Promise((resolve) => {
s3client.upload(
{
Bucket: bucketName,
/*
include the bucket name here. For some reason Localstack needs it.
see: github.com/localstack/localstack/i...
*/
Key: ${bucketName}/${name},
Body: data,
},
(err, response) => {
if (err) throw err
resolve(response)
},
)
})

module.exports = uploadFile

Hope that might be helpful for someone else in the future.

Salvador Hernandez • Jan 5 '20 • Edited

Great Doc! Had issues creating s3 bucket, had to configure aws configure with

accessKeyId: '123'
secretAccessKey: 'xyz`

otherwise it would throw the following error:
make_bucket failed: s3://demo-bucket Unable to locate credentials

RichardDrury • May 1 '20

This is brilliant, so well written and completely idiot proofed (for the likes of me). We won't be using it for the JS app you have created but more to have a local dev environment where we can spin up a docker container with a database and another with the S3 stack on it so we can develope data feeds.

You have contributed to my learning.
Thanks

Jeff Martin • Jul 31 '20

Nice article, Thanks for the work. To access the web ui you need to use the full version of localstack ie:
image: localstack/localstack-full:latest
The localstack github also warns that the web ui has been deprecated and may be removed at some point.

rkbadatya • Mar 14 '22 • Edited

It's no longer available

Nikola Janicijevic • Jan 30 '21

Nice work on this tutorial. I think that the last update of the localstack image move all ports to the 4566. Also there is a info that the dashboard will be removed in some of the upcoming releases.

Thanks for the work

Moji • Oct 23 '22 • Edited

hi friend, thanks for your Great article
i have also problem with accessing the ui of localStack with both Docker images (on post and localstack-latest) 2022-10-23
but i run my container with
localstack/localstack-full:0.11.6
and it works
thank you

Sergio Bilello • Jun 26 '19 • Edited

@Joseph great job but I was wondering why we get a warning. Do you have the same message in the log?
I have also to refresh the browse localhost:8055 2-3 times to see all the resources created.
Do you have the same problem?

localstack_demo_orig | 2019-06-26T17:57:57:DEBUG:localstack.services.s3.s3_listener: Found no <LastModified>(.*)</LastModified> inside response_content: list index out of range
localstack_demo_orig | WARNING: Unable to get details for bucket: [Errno 1] Operation not permitted: '/tmp/cache.fbd52520e8bfc4938a74ed8204e80533.json'
localstack_demo_orig | 2019-06-26T17:57:59:DEBUG:localstack.services.s3.s3_listener: Found no <LastModified>(.*)</LastModified> inside response_content: list index out of range
localstack_demo_orig | 2019-06-26T17:58:04:INFO:werkzeug: 127.0.0.1 - - [26/Jun/2019 17:58:04] "GET / HTTP/1.1" 200 -
localstack_demo_orig | 2019-06-26T17:58:04:DEBUG:localstack.services.s3.s3_listener: Found no <LastModified>(.*)</LastModified> inside response_content: list index out of

Joseph Thomas • Jun 28 '19

Hi Sergio,

I'm not sure why this is coming up - I don't remember seeing messages like this. It might be that your /tmp/ directory is not readable or writeable? This might be something to ask on Stack Overflow or on the Github page for localstack. Sorry I can't be of help!

Juliette • Oct 29 '19

Thank you for this Joseph!!

anaclaudiar • Nov 6 '19

Hi Joseph, great article! Thank you!
I think there is a small thing, you say "Add an image to your project directory and rename it to test-upload.jpg" but actually the js code expects test-image.jpg. Anyway, thanks for this, it helped me understand LocalStack.

Alexis Wilke • Sep 3 '19 • Edited

What's missing in your article is the fact that credentials can be whatever. You do show how to set it up, but you do that AFTER the:

aws s3 mb url

When it's already necessary on that line. Also you do not explain the fact that localstack will accept totally whatever as credentials.

Joseph Thomas • Sep 3 '19

Hi, thanks for pointing this out! I updated the setup with a new step:

Once the AWS CLI is installed, run aws configure to create some credentials. Even though we're talking to our "fake" local service, we still need credentials. You can enter real credentials (as described here), or dummy ones. Localstack requires that these details are present, but doesn't actually validate them.

Nippontradamus • Aug 9 '19

Hey @Joseph!

I am unable to see my bucket in the localhost:8055 page, however, I can see the bucket in the localhost:4572 page.

Great article though! I enjoyed reading it and was helpful in understanding the process. Keep it up

chan 🤖 • Feb 13 '22

For anyone who's encountered an error when using the latest module @aws-sdk/client-s3, use forcePathStyle instead of s3ForcePathStyle.

Ahmed Chouihi • Oct 24 '21

I have added also list objects function for anyone need to use it :

In aws.js
I have added this :

module.exports = listObjects

I have added other file named list-objects.js

const fs = require('fs')
const path = require('path')
const listObjects = require('./aws')

listObjects()

Yisus • Jul 8 '20

Awesome, very well explained. It has definitely helped me with the localstack setup. Thanks!

elmentecato • Jun 4 '19 • Edited

I had to add
s3BucketEndpoint: true
to the AWS.S3({ }) config in aws.js to make it work.

abduelwhidi2 • Jul 3 '19

Thanks for this article.
I am having issues running lambda functions on localstack. Did you guys try it out?
I started my aws service and seems working using the command.
docker run -e LAMBDA_EXECUTOR=docker -p 4574:4574 -e SERVICES=lambda -p 8080:8080 localstack/localstack &

I tried to upload a function, I have security issues
aws --endpoint-url=localhost:4574 lambda create-function --function-name=f1 --runtime=python2.7 --role=default --handler=lambda.handler --zip-file fileb://lambda.zip

But even the simple list does not work. I got:
Could not connect to the endpoint URL: "localhost:4574/2015-03-31/functions"

Thx
Abdu

Dean • Jun 24 '19

Great article, thank you! I think there is one small typo. You have a reference to http://localhost:8050 in the opening of your Docker Config section. Should it be http://localhost:8055?

Joseph Thomas • Jun 24 '19

Just fixed it, thanks for letting me know!

Tammy Lee • Oct 30 '19

This was a great walkthrough! Thank you so much, Joseph!
I'd never heard of Localstack before now and did everything probably the slowest and most manual way possible before.

JavaTec • Sep 25 '19

Hi Joseph, Great article, thank you. By any chance do you have a working example for Kinesis using localstack inside Docker?

Joseph Thomas • Sep 25 '19

Unfortunately, no - my experience with AWS doesn't go much further than S3, RDS & Lambdas.

JavaTec • Sep 26 '19

thank you for the reply!

Christophe • May 9 '19

Great article Joseph! Thank you... I think you have a natural gift for explaining things :-) ... I am looking forward to reading the next one.

Joseph Thomas • May 9 '19

Thank you! 😊

Jef LeCompte • Nov 21 '19

Love using localstack. Nice write up!

bugkerb • Jul 16 '19

Thanks Joseph! It's very nice article.

IsacNetero • May 14 '19

Thanks dude this was very helpful keep up the good work

Victor Duarte • Oct 18 '22

How do you handle hot reloading?
I was hoping I could have a fast way to iterate over local changes to my lambda functions, but I couldn't find a way to do so.