Simple S3-like server for development purposes, written in Go
Add README
+105
+105
README.md
+105
README.md
···
1
+
# gos3dir
2
+
3
+
A lightweight S3-compatible server that uses a local directory as storage.
4
+
Perfect for local development, testing, and offline S3 workflows.
5
+
_Do not use in production._
6
+
7
+
## Installation
8
+
9
+
```bash
10
+
go install tangled.org/juanlu.space/gos3dir@latest
11
+
```
12
+
13
+
Or build from source:
14
+
15
+
```bash
16
+
git clone <repository-url>
17
+
cd gos3dir
18
+
go build
19
+
```
20
+
21
+
## Usage
22
+
23
+
Start the server by pointing it to a directory:
24
+
25
+
```bash
26
+
gos3dir /path/to/data/dir
27
+
```
28
+
29
+
The server listens on `http://localhost:8041`.
30
+
31
+
## Configure AWS CLI v2
32
+
33
+
Add a profile to `~/.aws/config`:
34
+
35
+
```ini
36
+
[profile gos3dir-dev]
37
+
endpoint_url = http://localhost:8041
38
+
s3 =
39
+
addressing_style = path
40
+
```
41
+
42
+
Add dummy credentials to `~/.aws/credentials`:
43
+
44
+
```ini
45
+
[gos3dir-dev]
46
+
aws_access_key_id = test
47
+
aws_secret_access_key = test
48
+
```
49
+
50
+
## Examples
51
+
52
+
List buckets:
53
+
```bash
54
+
aws s3 ls --profile gos3dir-dev
55
+
```
56
+
57
+
Create a bucket:
58
+
```bash
59
+
aws s3 mb s3://my-bucket --profile gos3dir-dev
60
+
```
61
+
62
+
Upload a file:
63
+
```bash
64
+
aws s3 cp file.txt s3://my-bucket/ --profile gos3dir-dev
65
+
```
66
+
67
+
List objects in a bucket:
68
+
```bash
69
+
aws s3 ls s3://my-bucket --profile gos3dir-dev
70
+
```
71
+
72
+
Delete an object:
73
+
```bash
74
+
aws s3 rm s3://my-bucket/file.txt --profile gos3dir-dev
75
+
```
76
+
77
+
Delete an empty bucket:
78
+
```bash
79
+
aws s3 rb s3://my-bucket --profile gos3dir-dev
80
+
```
81
+
82
+
## Supported Operations
83
+
84
+
- List buckets (`GET /`)
85
+
- List objects (`GET /{bucket}`)
86
+
- Create bucket (`PUT /{bucket}`)
87
+
- Upload object (`PUT /{bucket}/{key}`)
88
+
- Delete empty bucket (`DELETE /{bucket}`)
89
+
- Delete object (`DELETE /{bucket}/{key}`)
90
+
91
+
## Future work
92
+
93
+
We would like to fix these at some point:
94
+
- Downloads
95
+
- Proper deletion of dangling "directories"
96
+
97
+
## Limitations
98
+
99
+
These are by design and will not be fixed:
100
+
- Path-style addressing only (virtual-hosted-style not supported)
101
+
- No authentication or authorization
102
+
- No multipart uploads
103
+
- No versioning
104
+
- No ETags for uploaded objects
105
+
- No bit-by-bit compatibility with Amazon S3 server responses