{ errMsg }
8 |9 | 10 | ← Go Back 11 | 12 |
13 |
32 |
33 | 
38 |
39 | 
44 |
45 | ---
46 |
47 | ## Setup:
48 |
49 | Besides the obvious prerequisite of having Go! on your machine, you must have Air installed for hot reloading when editing code.
50 |
51 | Start the app in development mode:
52 |
53 | ```
54 | $ air # Ctrl + C to stop the application
55 | ```
56 |
57 | Build for production:
58 |
59 | ```
60 | $ go build -ldflags="-s -w" -o ./bin/main . # ./bin/main to run the application
61 | ```
62 |
63 | >***In order to have autocompletion and syntax highlighting in VS Code for the Teml templating language, you will have to install the [templ-vscode](https://marketplace.visualstudio.com/items?itemName=a-h.templ) extension (for vim/nvim install this [plugin](https://github.com/joerdav/templ.vim)). To generate the Go code corresponding to these templates you will have to download this [executable binary](https://github.com/a-h/templ/releases/tag/v0.2.476) from Github and place it in the PATH of your system. The command:***
64 |
65 | ```
66 | $ templ generate --watch
67 | ```
68 |
69 | >***Will allow us to watch the .templ files and compile them as we save. Review the documentation on Templ [installation](https://templ.guide/quick-start/installation) and [support](https://templ.guide/commands-and-tools/ide-support/) for your IDE.***
70 |
71 | ---
72 |
73 | ### Happy coding 😀!!',
74 | 'A full-stack application using Golang´s Fiber framework.'
75 | );
76 | -- +goose StatementEnd
77 |
78 | -- +goose Down
79 | -- +goose StatementBegin
80 | DELETE FROM posts ORDER BY id DESC LIMIT 1;
81 | -- +goose StatementEnd
82 |
--------------------------------------------------------------------------------
/internal/app/api/api.go:
--------------------------------------------------------------------------------
1 | package api
2 |
3 | import (
4 | "log/slog"
5 | "net/http"
6 | "os"
7 | "regexp"
8 |
9 | "github.com/a-h/templ"
10 | "github.com/emarifer/gocms/internal/service"
11 | "github.com/emarifer/gocms/settings"
12 | "github.com/gin-contrib/gzip"
13 | "github.com/gin-gonic/gin"
14 | "github.com/gomarkdown/markdown"
15 | "github.com/gomarkdown/markdown/html"
16 | "github.com/gomarkdown/markdown/parser"
17 | )
18 |
19 | type API struct {
20 | serv service.Service
21 | logger *slog.Logger
22 | settings *settings.AppSettings
23 | }
24 |
25 | func New(
26 | serv service.Service, logger *slog.Logger, settings *settings.AppSettings,
27 | ) *API {
28 |
29 | return &API{
30 | serv: serv,
31 | logger: logger,
32 | settings: settings,
33 | }
34 | }
35 |
36 | type generator = func(*gin.Context) ([]byte, *customError)
37 |
38 | var re = regexp.MustCompile(`Table|refused`)
39 |
40 | func (a *API) Start(
41 | e *gin.Engine, address string, cache *Cache,
42 | ) (*gin.Engine, error) {
43 | e.Use(gzip.Gzip(gzip.DefaultCompression)) // gzip compression middleware
44 | e.Use(a.globalErrorHandler()) // Error handler middleware
45 | e.MaxMultipartMemory = 1 // 8 MiB max. request
46 |
47 | e.Static("/assets", "./assets")
48 | e.Static("/media", a.settings.ImageDirectory)
49 | // e.LoadHTMLGlob("views/**/*") // Used for Go Html templates
50 |
51 | a.registerRoutes(e, cache)
52 |
53 | // SEE NOTE BELOW (this is hacky):
54 | if os.Getenv("GO_ENV") == "testing" {
55 |
56 | return e, nil
57 | } else {
58 |
59 | return nil, e.Run(address)
60 | }
61 | }
62 |
63 | func (a *API) registerRoutes(e *gin.Engine, cache *Cache) {
64 | // ↓ injected into the Start function ↓
65 | // logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
66 | // cache := MakeCache(4, time.Minute*1)
67 |
68 | // All cache-able endpoints
69 | a.addCachableHandler(e, "GET", "/", a.homeHandler, cache)
70 | a.addCachableHandler(e, "GET", "/post/:id", a.postHandler, cache)
71 | a.addCachableHandler(e, "GET", "/contact", a.contactHandler, cache)
72 |
73 | // Do not cache as it needs to handle new form values
74 | e.POST("/contact-send", a.contactFormHandler)
75 | }
76 |
77 | // mdToHTML converts markdown to HTML
78 | func (a *API) mdToHTML(md []byte) []byte {
79 | // create markdown parser with extensions
80 | extensions := parser.CommonExtensions | parser.AutoHeadingIDs | parser.NoEmptyLineBeforeBlock
81 | p := parser.NewWithExtensions(extensions)
82 | doc := p.Parse(md)
83 |
84 | // create HTML renderer with extensions
85 | htmlFlags := html.CommonFlags | html.HrefTargetBlank
86 | opts := html.RendererOptions{Flags: htmlFlags}
87 | renderer := html.NewRenderer(opts)
88 |
89 | return markdown.Render(doc, renderer)
90 | }
91 |
92 | // renderView will render the templ component into
93 | // a gin context's Response Writer
94 | func (a *API) renderView(
95 | c *gin.Context, status int, cmp templ.Component,
96 | ) error {
97 | c.Status(status)
98 |
99 | return cmp.Render(c.Request.Context(), c.Writer)
100 | }
101 |
102 | func (a *API) addCachableHandler(
103 | e *gin.Engine, method, endpoint string, gen generator, cache *Cache,
104 | ) {
105 |
106 | handler := func(c *gin.Context) {
107 | var errCache error
108 | // if endpoint is cached, get it from cache
109 | cachedEndpoint, errCache := (*cache).Get(c.Request.RequestURI)
110 | if errCache == nil {
111 | c.Data(
112 | http.StatusOK,
113 | "text/html; charset=utf-8",
114 | cachedEndpoint.Contents,
115 | )
116 |
117 | return
118 | } else {
119 | a.logger.Info(
120 | "cache info",
121 | slog.String("could not get page from cache", errCache.Error()),
122 | )
123 | }
124 |
125 | // If the endpoint data is not recovered, the handler (gen) is called
126 | html_buffer, err := gen(c)
127 | if err != nil {
128 | c.Error(err)
129 |
130 | return
131 | }
132 |
133 | // After handler call, add to cache
134 | errCache = (*cache).Store(c.Request.RequestURI, html_buffer)
135 | if errCache != nil {
136 | a.logger.Warn(
137 | "cache warning",
138 | slog.String("could not add page to cache", errCache.Error()),
139 | )
140 | }
141 |
142 | c.Data(http.StatusOK, "text/html; charset=utf-8", html_buffer)
143 | }
144 |
145 | // Hacky
146 | switch method {
147 | case "GET":
148 | e.GET(endpoint, handler)
149 | case "POST":
150 | e.POST(endpoint, handler)
151 | case "DELETE":
152 | e.DELETE(endpoint, handler)
153 | case "PUT":
154 | e.PUT(endpoint, handler)
155 | }
156 | }
157 |
158 | /* HOW DO I KNOW I'M RUNNING WITHIN "GO TEST". SEE:
159 | https://stackoverflow.com/questions/14249217/how-do-i-know-im-running-within-go-test#59444829
160 | */
161 |
--------------------------------------------------------------------------------
/internal/repository/post.repository.go:
--------------------------------------------------------------------------------
1 | package repository
2 |
3 | import (
4 | "context"
5 |
6 | "github.com/emarifer/gocms/internal/entity"
7 | )
8 |
9 | const (
10 | qryInsertPost = `
11 | INSERT INTO posts (title, excerpt, content)
12 | VALUES (:title, :excerpt, :content);
13 | `
14 |
15 | qryGetPostById = `
16 | SELECT * FROM posts
17 | WHERE id = ?;
18 | `
19 |
20 | qryGetAllPosts = `
21 | SELECT * FROM posts
22 | ORDER BY created_at DESC;
23 | `
24 |
25 | qryUpdatePostTitle = `
26 | UPDATE posts
27 | SET title = ?
28 | WHERE id = ?;
29 | `
30 |
31 | qryUpdatePostExcerpt = `
32 | UPDATE posts
33 | SET excerpt = ?
34 | WHERE id = ?;
35 | `
36 |
37 | qryUpdatePostContent = `
38 | UPDATE posts
39 | SET content = ?
40 | WHERE id = ?;
41 | `
42 |
43 | qryDeletePost = `
44 | DELETE FROM posts
45 | WHERE id = ?;
46 | `
47 | )
48 |
49 | // SavePost inserts a record into the database
50 | // passing the title, excerpt and content
51 | func (r *repo) SavePost(ctx context.Context, post *entity.Post) (int, error) {
52 | result, err := r.db.NamedExecContext(ctx, qryInsertPost, post)
53 | if err != nil {
54 | return -1, err
55 | }
56 |
57 | lastId, err := result.LastInsertId() // SEE NOTE BELOW
58 | if err != nil {
59 | return -1, err
60 | }
61 |
62 | return int(lastId), nil
63 | }
64 |
65 | // GetPosts gets all the posts from the current
66 | // database
67 | func (r *repo) GetPosts(ctx context.Context) ([]entity.Post, error) {
68 | pp := []entity.Post{}
69 |
70 | err := r.db.SelectContext(ctx, &pp, qryGetAllPosts)
71 | if err != nil {
72 | return nil, err
73 | }
74 |
75 | return pp, nil
76 | }
77 |
78 | // GetPost gets a post from the database
79 | // with the given ID.
80 | func (r *repo) GetPost(ctx context.Context, id int) (*entity.Post, error) {
81 | p := &entity.Post{}
82 |
83 | err := r.db.GetContext(ctx, p, qryGetPostById, id)
84 | if err != nil {
85 | return nil, err
86 | }
87 |
88 | return p, nil
89 | }
90 |
91 | // UpdatePost updates a post from the database.
92 | // with the ID and data provided.
93 | func (r *repo) UpdatePost(
94 | ctx context.Context, post *entity.Post,
95 | ) (int64, error) {
96 | var row int64
97 | tx, err := r.db.Beginx()
98 | if err != nil {
99 | return -1, err
100 | }
101 | defer tx.Rollback()
102 |
103 | if len(post.Title) > 0 {
104 | result, err := tx.ExecContext(
105 | ctx, qryUpdatePostTitle, post.Title, post.ID,
106 | )
107 | if err != nil {
108 | return -1, err
109 | }
110 |
111 | if row, err = result.RowsAffected(); err != nil {
112 | return -1, err
113 | } else if row == 0 {
114 | return -1, err
115 | }
116 | }
117 |
118 | if len(post.Excerpt) > 0 {
119 | result, err := tx.ExecContext(
120 | ctx, qryUpdatePostExcerpt, post.Excerpt, post.ID,
121 | )
122 | if err != nil {
123 | return -1, err
124 | }
125 |
126 | if row, err = result.RowsAffected(); err != nil {
127 | return -1, err
128 | } else if row == 0 {
129 | return -1, err
130 | }
131 | }
132 |
133 | if len(post.Content) > 0 {
134 | result, err := tx.ExecContext(
135 | ctx, qryUpdatePostContent, post.Content, post.ID,
136 | )
137 | if err != nil {
138 | return -1, err
139 | }
140 |
141 | if row, err = result.RowsAffected(); err != nil {
142 | return -1, err
143 | } else if row == 0 {
144 | return -1, err
145 | }
146 | }
147 |
148 | if err = tx.Commit(); err != nil {
149 | return -1, err
150 | }
151 |
152 | return row, nil
153 | }
154 |
155 | // DeletePost delete a post from the database
156 | // with the given ID.
157 | func (r *repo) DeletePost(ctx context.Context, id int) (int64, error) {
158 | var row int64
159 |
160 | result, err := r.db.ExecContext(ctx, qryDeletePost, id)
161 | if err != nil {
162 | return -1, err
163 | }
164 |
165 | if row, err = result.RowsAffected(); err != nil {
166 | return -1, err
167 | } else if row == 0 {
168 | return -1, err
169 | }
170 |
171 | return row, nil
172 | }
173 |
174 | /* How to get id of last inserted row from sqlx?. SEE:
175 | https://stackoverflow.com/questions/53990799/how-to-get-id-of-last-inserted-row-from-sqlx
176 |
177 | Using database/sql you have to close the rows with:
178 |
179 | defer func() {
180 | err = errors.Join(rows.Close())
181 | }()
182 |
183 | Or simply:
184 |
185 | defer rows.Close()
186 |
187 | But with github.com/jmoiron/sqlx it is no longer necessary, it is not even necessary to open them to be able to scan them and the library itself takes care of everything. SEE:
188 | https://www.youtube.com/watch?v=R-x9j5blTzI&list=PLZ51_5WcvDvCzCB2nwm8AWodXoBbaO3Iw&index=9&t=8300s
189 |
190 | IF THIS IS NOT DONE, USING DATABASE/SQL, WILL CAUSE A DATABASE CRASH WHEN PERFORMING BENCHMARK TESTS, WHICH GENERATE MANY REQUESTS PER SECOND.
191 | */
192 |
--------------------------------------------------------------------------------
/cmd/gocms/main.go:
--------------------------------------------------------------------------------
1 | package main
2 |
3 | import (
4 | "context"
5 | "flag"
6 | "fmt"
7 | "log/slog"
8 | "os"
9 | "time"
10 |
11 | "github.com/emarifer/gocms/database"
12 | "github.com/emarifer/gocms/internal/app/api"
13 | "github.com/emarifer/gocms/internal/repository"
14 | "github.com/emarifer/gocms/internal/service"
15 | "github.com/emarifer/gocms/settings"
16 | "github.com/gin-gonic/gin"
17 | "go.uber.org/fx"
18 | )
19 |
20 | func main() {
21 | gocms := fx.New(
22 | fx.Provide(
23 | context.Background,
24 | func() *os.File { return os.Stdout },
25 | func() *slog.JSONHandler {
26 | return slog.NewJSONHandler(os.Stdout, nil)
27 | },
28 | func(h *slog.JSONHandler) *slog.Logger { return slog.New(h) },
29 | func(l *slog.Logger) *string {
30 | config_toml := flag.String("config", "", "path to the config to be used")
31 | flag.Parse()
32 | l.Info("reading config file", "from path", config_toml)
33 |
34 | return config_toml
35 | },
36 | settings.New,
37 | database.NewMariaDBConnection,
38 | repository.New,
39 | service.New,
40 | gin.Default,
41 | api.New,
42 | ),
43 |
44 | fx.Invoke(
45 | setLifeCycle,
46 | ),
47 | )
48 |
49 | gocms.Run()
50 | }
51 |
52 | func setLifeCycle(
53 | lc fx.Lifecycle,
54 | a *api.API,
55 | s *settings.AppSettings,
56 | e *gin.Engine,
57 | ) {
58 | lc.Append(fx.Hook{
59 | OnStart: func(ctx context.Context) error {
60 | address := fmt.Sprintf(":%d", s.WebserverPort)
61 | cache := api.MakeCache(4, time.Minute*10)
62 | go func() {
63 | // e.Logger.Fatal(a.Start(e, address))
64 | a.Start(e, address, &cache)
65 | }()
66 |
67 | return nil
68 | },
69 | OnStop: func(ctx context.Context) error {
70 | // return e.Close()
71 | return nil
72 | },
73 | })
74 | }
75 |
76 | /* REFERENCES:
77 | https://www.youtube.com/playlist?list=PLZ51_5WcvDvDBhgBymjAGEk0SR1qmOh4q
78 | https://github.com/matheusgomes28/urchin
79 |
80 | https://github.com/golang-standards/project-layout
81 | https://www.hostinger.es/tutoriales/headless-cms
82 | https://www.bacancytechnology.com/blog/golang-web-frameworks
83 | https://github.com/gin-gonic/gin
84 |
85 | Gin vs. Echo:
86 | https://www.codeavail.com/blog/gin-vs-echo/
87 |
88 | The client-side-templates Extension for HTMX:
89 | https://htmx.org/extensions/client-side-templates/
90 |
91 | Error handler middleware:
92 | https://blog.ruangdeveloper.com/membuat-global-error-handler-go-gin/
93 |
94 | Model binding and validation:
95 | https://gin-gonic.com/docs/examples/binding-and-validation/
96 | https://gin-gonic.com/docs/examples/bind-uri/
97 | https://dev.to/ankitmalikg/api-validation-in-gin-ensuring-data-integrity-in-your-api-2p40#:~:text=To%20perform%20input%20validation%20in,query%20parameters%2C%20and%20request%20bodies.
98 | https://www.google.com/search?q=validation+function+gin&oq=validation+function+gin&aqs=chrome..69i57j33i160j33i671.11287j0j7&sourceid=chrome&ie=UTF-8
99 |
100 | Go: how to check if a string contains multiple substrings?:
101 | https://stackoverflow.com/questions/47131996/go-how-to-check-if-a-string-contains-multiple-substrings#47134680
102 |
103 | Debugging Go with VSCode and Air:
104 | https://www.arhea.net/posts/2023-08-25-golang-debugging-with-air-and-vscode/
105 |
106 | What is the purpose of .PHONY in a Makefile?:
107 | https://stackoverflow.com/questions/2145590/what-is-the-purpose-of-phony-in-a-makefile
108 |
109 | A-H.TEMPL:
110 | https://templ.guide/syntax-and-usage/template-composition/
111 | https://templ.guide/syntax-and-usage/rendering-raw-html/
112 |
113 | INJECTION OF A LOGGER WITH FX:
114 | https://uber-go.github.io/fx/container.html#providing-values
115 |
116 | USING LOG/SLOG:
117 | https://www.youtube.com/watch?v=bDpB6k-Q_GY
118 | https://github.com/disturb16/go_examples/tree/main/btrlogs
119 | https://betterstack.com/community/guides/logging/logging-in-go/
120 | https://go.dev/blog/slog
121 |
122 | SHARDEDMAP:
123 | https://pkg.go.dev/github.com/zutto/shardedmap?utm_source=godoc
124 | https://github.com/zutto/shardedmap
125 |
126 | BENCHMARK WITH/WITHOUT CACHE:
127 | https://github.com/fcsonline/drill
128 |
129 | COMMAND-LINE FLAGS:
130 | https://gobyexample.com/command-line-flags
131 |
132 | DECODING AND ENCODING OF TOML FILES:
133 | https://github.com/BurntSushi/toml
134 | https://godocs.io/github.com/BurntSushi/toml
135 |
136 | MISCELLANEOUS:
137 | https://github.com/a-h/templ/tree/1f30f822a6edfdbfbab9e6851b1ff61e0ab01d4f/examples/integration-gin
138 |
139 | https://github.com/stackus/todos
140 |
141 | https://toml.io/en/
142 |
143 | https://github.com/pelletier/go-toml
144 |
145 | [Git: See my last commit]
146 | https://stackoverflow.com/questions/2231546/git-see-my-last-commit
147 | */
148 |
149 | /* CHECKS FUNCTIONS:
150 |
151 | // settings test:
152 | func(s *settings.Settings) {
153 | fmt.Println(s.DB.Name)
154 | },
155 |
156 | // Database operation check function:
157 | func(db *sqlx.DB) {
158 | _, err := db.Query("SELECT * FROM users")
159 | if err != nil {
160 | panic(err)
161 | }
162 | },
163 | */
164 |
--------------------------------------------------------------------------------
/docker/docker-compose.yml:
--------------------------------------------------------------------------------
1 | version: '3.8'
2 |
3 | services:
4 | gocms:
5 | image: emarifer/gocms:0.1
6 | ports:
7 | - "8080:8080"
8 | - "8081:8081"
9 | volumes:
10 | - type: bind
11 | source: ..
12 | target: /gocms
13 | volume:
14 | nocopy: true
15 | command: /gocms/docker/start-app.sh
16 | depends_on:
17 | mariadb:
18 | condition: service_healthy
19 | restart: on-failure
20 | networks:
21 | - common-net
22 |
23 | mariadb:
24 | image: mariadb:jammy
25 | container_name: mariadb
26 | volumes:
27 | - ../mariadb_init:/docker-entrypoint-initdb.d
28 | environment:
29 | MARIADB_ROOT_PASSWORD: my-secret-pw
30 | healthcheck:
31 | test: [ "CMD", "mariadb", "-uroot", "-pmy-secret-pw", "-e", "USE cms_db" ]
32 | interval: 10s
33 | timeout: 10s
34 | retries: 10
35 | networks:
36 | - common-net
37 |
38 | networks:
39 | common-net: {}
40 |
41 | # docker exec -it mariadb mariadb -uroot -pmy-secret-pw [mariadb container]
42 | # docker exec -it docker-gocms-1 sh [docker-gocms-1 container]
43 | # command & regular expression to capture the volume id/name:
44 | # docker container inspect mariadb | egrep '\"Name\": \"[0-9a-f]{64}\"'
45 | # VIEWING CONTAINER SIZE:
46 | # https://docs.docker.com/reference/cli/docker/inspect/
47 | # https://refine.dev/blog/docker-list-containers/#viewing-container-size:
48 | # docker ps --size (Only running containers)
49 | # HOW TO GET THE CREATION DATE OF A DOCKER VOLUME:
50 | # https://stackoverflow.com/questions/75150068/how-to-get-the-creation-date-of-a-docker-volume
51 | # COMMAND:
52 | # docker volume ls --quiet | xargs docker volume inspect --format '{{ .CreatedAt }} {{ .Name }}' | sort
53 | # HOW TO INSPECT VOLUMES SIZE IN DOCKER:
54 | # https://medium.com/homullus/how-to-inspect-volumes-size-in-docker-de1068d57f6b
55 | # docker system df -v | grep cd6ec (e.g.)
56 | # DETECT DUBIOUS OWNERSHIP IN REPOSITORY AT DOCKER CONTAINER:
57 | # https://docs.docker.com/compose/compose-file/compose-file-v3/#volumes
58 | # https://community.jenkins.io/t/detected-dubious-ownership-in-repository-with-jenkins-upgrade/6182
59 |
60 | # =========== OTHER REFERENCES (1) ===========
61 | # https://iesgn.github.io/curso_docker_2021/sesion3/volumenes.html
62 |
63 | # https://docs.docker.com/storage/bind-mounts/
64 |
65 | # (VOLUMES 'NOCOPY')
66 | # https://stackoverflow.com/questions/38287388/docker-and-volumes-nocopy
67 | # https://github.com/docker/docs/issues/2992#issuecomment-299596714
68 |
69 | # https://stackoverflow.com/questions/51313852/docker-compose-cannot-connect-to-database
70 |
71 | # https://docs.docker.com/compose/startup-order/
72 | # https://docs.docker.com/compose/compose-file/05-services/#depends_on
73 | # https://www.warp.dev/terminus/docker-compose-depends-on
74 | # https://docs.docker.com/compose/compose-file/05-services/#healthcheck
75 | # https://www.google.com/search?q=mariadb+healthcheck+db+created&oq=mariadb+healthcheck+db+created&aqs=chrome..69i57j33i160l2.3778j0j7&sourceid=chrome&ie=UTF-8
76 | # https://kuttler.eu/code/docker-compose-mariadb-mysql-healthcheck/
77 | # https://www.google.com/search?q=set+-euo+pipefail&oq=set+-euo+pipefail&aqs=chrome..69i57.1859395j0j7&sourceid=chrome&ie=UTF-8
78 | # https://gist.github.com/mohanpedala/1e2ff5661761d3abd0385e8223e16425?permalink_comment_id=3935570
79 |
80 | # (USE A RESTART POLICY [START CONTAINERS AUTOMATICALLY])
81 | # https://docker-docs.uclv.cu/config/containers/start-containers-automatically/#use-a-restart-policy
82 | # restart: on-failure
83 |
84 | # (HOW TO CLEAR DOCKER CACHE)
85 | # https://tech.forums.softwareag.com/t/how-to-clear-docker-cache/283214
86 | # docker system prune -a
87 |
88 | # (DOCKER VOLUME PRUNE NOT DELETING UNUSED VOLUMES)
89 | # https://stackoverflow.com/questions/75493720/docker-volume-prune-not-deleting-unused-volumes
90 | # docker volume prune --filter all=1
91 |
92 | # =========== OTHER REFERENCES (2) ===========
93 | # docker compose up -d
94 |
95 | # docker exec -it gocms-db mariadb --user root -p # or alternatively:
96 | # docker exec -it gocms-db mariadb -uroot -pmy-secret-pw
97 | # (Enter password:my-secret-pw)
98 | # show databases;
99 | # use cms_db;
100 | # show tables;
101 | # show columns from posts; // describe posts; (is the same)
102 | # get the last 4 records from the "images" table:
103 | # SELECT * FROM images ORDER BY created_at DESC LIMIT 4;
104 |
105 | # Bootstrap with development data. SEE:
106 | # https://www.beekeeperstudio.io/blog/how-to-use-mariadb-with-docker
107 |
108 | # CURRENT TIMESTAMP IN MARIADB. SEE:
109 | # https://mariadb.com/kb/en/timestamp/
110 | # https://stackoverflow.com/questions/40864951/mariadb-current-timestamp-default
111 |
112 | # USING GOOSE:
113 | # export GOOSE_DRIVER=mysql
114 | # export GOOSE_DBSTRING="root:my-secret-pw@tcp(localhost:3306)/cms_db"
115 | # MAIN COMMANDS:
116 | # goose create add_sample_post sql
117 | # goose up / goose down
118 | # REST OF COMMANDS:
119 | # https://citizix.com/managing-database-migrations-with-golang-goose-using-incremental-sql-changes/
120 | # https://github.com/pressly/goose
121 |
--------------------------------------------------------------------------------
/settings/settings.go:
--------------------------------------------------------------------------------
1 | package settings
2 |
3 | import (
4 | // _ "embed"
5 |
6 | "fmt"
7 | "log"
8 | "os"
9 | "strconv"
10 |
11 | "github.com/BurntSushi/toml"
12 | // "gopkg.in/yaml.v3"
13 | )
14 |
15 | /* //go:embed settings.yaml
16 | var settingsFile []byte
17 |
18 | type DatabaseConfig struct {
19 | Host string `yaml:"host"`
20 | Port int `yaml:"port"`
21 | User string `yaml:"user"`
22 | Password string `yaml:"password"`
23 | Name string `yaml:"name"`
24 | }
25 |
26 | type Settings struct {
27 | Port string `yaml:"port"`
28 | AdminPort string `yaml:"admin-port"`
29 | DB DatabaseConfig `yaml:"database"`
30 | } */
31 |
32 | type Shortcode struct {
33 | Name string `toml:"name"` // name for the shortcode {{ name:…:…}}
34 | Plugin string `toml:"plugin"` // the lua plugin path
35 | }
36 |
37 | type AppSettings struct {
38 | WebserverPort int `toml:"webserver_port"`
39 | AdminWebserverPort int `toml:"admin_webserver_port"`
40 | DatabaseHost string `toml:"database_host"`
41 | DatabasePort int `toml:"database_port"`
42 | DatabaseUser string `toml:"database_user"`
43 | DatabasePassword string `toml:"database_password"`
44 | DatabaseName string `toml:"database_name"`
45 | ImageDirectory string `toml:"image_dir"`
46 | Shortcodes []Shortcode `toml:"shortcodes"`
47 | }
48 |
49 | func New(filepath *string) (*AppSettings, error) {
50 | var s *AppSettings
51 |
52 | if *filepath != "" {
53 | log.Printf("reading config file %s", *filepath)
54 | settings, err := ReadConfigToml(filepath)
55 | if err != nil {
56 | return nil, err
57 | }
58 |
59 | s = settings
60 | } else {
61 | log.Println("no config file, reading environment variables")
62 | settings, err := LoadSettings()
63 | if err != nil {
64 | return nil, err
65 | }
66 |
67 | s = settings
68 | }
69 |
70 | return s, nil
71 | }
72 |
73 | func LoadSettings() (*AppSettings, error) {
74 | // Want to load the environment variables
75 | var appSettings *AppSettings
76 |
77 | webserver_port_str := os.Getenv("WEBSERVER_PORT")
78 | if webserver_port_str == "" {
79 | webserver_port_str = "8080"
80 | }
81 |
82 | webserver_port, err := strconv.Atoi(webserver_port_str)
83 | if err != nil {
84 | return appSettings, fmt.Errorf(
85 | "WEBSERVER_PORT is not valid: %v", err,
86 | )
87 | }
88 |
89 | admin_webserver_port_str := os.Getenv("ADMIN_WEBSERVER_PORT")
90 | if admin_webserver_port_str == "" {
91 | admin_webserver_port_str = "8081"
92 | }
93 |
94 | admin_webserver_port, err := strconv.Atoi(admin_webserver_port_str)
95 | if err != nil {
96 | return appSettings, fmt.Errorf(
97 | "ADMIN_WEBSERVER_PORT is not valid: %v", err,
98 | )
99 | }
100 |
101 | database_host := os.Getenv("DATABASE_HOST")
102 | if len(database_host) == 0 {
103 | return appSettings, fmt.Errorf("DATABASE_HOST is not defined")
104 | }
105 |
106 | database_port_str := os.Getenv("DATABASE_PORT")
107 | if len(database_port_str) == 0 {
108 | return appSettings, fmt.Errorf("DATABASE_PORT is not defined")
109 | }
110 |
111 | database_port, err := strconv.Atoi(database_port_str)
112 | if err != nil {
113 | return appSettings, fmt.Errorf("DATABASE_PORT is not a valid integer: %v", err)
114 | }
115 |
116 | database_user := os.Getenv("DATABASE_USER")
117 | if len(database_user) == 0 {
118 | return appSettings, fmt.Errorf("DATABASE_USER is not defined")
119 | }
120 |
121 | database_password := os.Getenv("DATABASE_PASSWORD")
122 | if len(database_password) == 0 {
123 | return appSettings, fmt.Errorf("DATABASE_PASSWORD is not defined")
124 | }
125 |
126 | database_name := os.Getenv("DATABASE_NAME")
127 | if len(database_name) == 0 {
128 | return appSettings, fmt.Errorf("DATABASE_NAME is not defined")
129 | }
130 |
131 | image_directory := os.Getenv("IMAGE_DIRECTORY")
132 | if len(image_directory) == 0 {
133 | return appSettings, fmt.Errorf("IMAGE_DIRECTORY is not defined")
134 | }
135 |
136 | config_file_path := os.Getenv("CONFIG_FILE_PATH")
137 | if len(config_file_path) == 0 {
138 | return appSettings, fmt.Errorf("CONFIG_FILE_PATH is not defined")
139 | }
140 |
141 | s, err := ReadConfigToml(&config_file_path)
142 | if err != nil {
143 | return appSettings, fmt.Errorf(
144 | "CONFIG_FILE_PATH is not valid: %v", err,
145 | )
146 | }
147 |
148 | return &AppSettings{
149 | WebserverPort: webserver_port,
150 | AdminWebserverPort: admin_webserver_port,
151 | DatabaseHost: database_host,
152 | DatabaseUser: database_user,
153 | DatabasePassword: database_password,
154 | DatabasePort: database_port,
155 | DatabaseName: database_name,
156 | ImageDirectory: image_directory,
157 | Shortcodes: s.Shortcodes,
158 | }, nil
159 | }
160 |
161 | func ReadConfigToml(filepath *string) (*AppSettings, error) {
162 | /* var s Settings
163 |
164 | err := yaml.Unmarshal(settingsFile, &s)
165 | if err != nil {
166 | return nil, err
167 | }
168 |
169 | return &s, nil */
170 | var s AppSettings
171 |
172 | _, err := toml.DecodeFile(*filepath, &s)
173 | if err != nil {
174 | return nil, err
175 | }
176 |
177 | return &s, nil
178 | }
179 |
--------------------------------------------------------------------------------
/tests/system_tests/helpers/helpers.go:
--------------------------------------------------------------------------------
1 | package helpers
2 |
3 | import (
4 | "context"
5 | "embed"
6 | "fmt"
7 | "log/slog"
8 | "os"
9 | "time"
10 |
11 | "github.com/emarifer/gocms/database"
12 | admin_api "github.com/emarifer/gocms/internal/admin_app/api"
13 | "github.com/emarifer/gocms/internal/app/api"
14 | "github.com/emarifer/gocms/internal/repository"
15 | "github.com/emarifer/gocms/internal/service"
16 | "github.com/emarifer/gocms/settings"
17 | "github.com/gin-gonic/gin"
18 | "github.com/go-playground/validator/v10"
19 |
20 | sqle "github.com/dolthub/go-mysql-server"
21 | "github.com/dolthub/go-mysql-server/memory"
22 | "github.com/dolthub/go-mysql-server/server"
23 | "github.com/dolthub/go-mysql-server/sql"
24 | "github.com/jmoiron/sqlx"
25 |
26 | _ "github.com/go-sql-driver/mysql"
27 | )
28 |
29 | //go:embed migrations/*.sql
30 | var EmbedMigrations embed.FS
31 |
32 | // SEE NOTE BELOW:
33 | func init() {
34 | os.Setenv("GO_ENV", "testing")
35 | }
36 |
37 | func RunDatabaseServer(as settings.AppSettings) {
38 | pro := CreateTestDatabase(as.DatabaseName)
39 | engine := sqle.NewDefault(pro)
40 | engine.Analyzer.Catalog.MySQLDb.AddRootAccount()
41 |
42 | session := memory.NewSession(sql.NewBaseSession(), pro)
43 | ctx := sql.NewContext(context.Background(), sql.WithSession(session))
44 | ctx.SetCurrentDatabase(as.DatabaseName)
45 |
46 | config := server.Config{
47 | Protocol: "tcp",
48 | Address: fmt.Sprintf("%s:%d", as.DatabaseHost, as.DatabasePort),
49 | }
50 | s, err := server.NewServer(config, engine, memory.NewSessionBuilder(pro), nil)
51 | if err != nil {
52 | panic(err)
53 | }
54 | if err = s.Start(); err != nil {
55 | panic(err)
56 | }
57 | }
58 |
59 | func CreateTestDatabase(name string) *memory.DbProvider {
60 | db := memory.NewDatabase(name)
61 | db.BaseDatabase.EnablePrimaryKeyIndexes()
62 |
63 | pro := memory.NewDBProvider(db)
64 |
65 | return pro
66 | }
67 |
68 | func WaitForDb(ctx context.Context, as settings.AppSettings) (*sqlx.DB, error) {
69 | // can be done
7 |
8 | 
11 |
12 |
13 | 14 |
21 |
22 | Shortify
9 | 10 |
11 |
12 | 13 | 14 |
15 | 16 | A Full Stack Url Shortener App using Golang\'s Echo framework + HTMX & Templ. 17 | 18 |
19 | 20 |23 | 24 | ## 🤔 What Stack have we used? 25 | 26 | In the implementation of this application we have used the following technologies: 27 | 28 | - ✅ **Bootstrapping**: [Go programming language (v1.21)](https://go.dev/) 29 | - ✅ **Backend Framework**: [Echo v4.11.4 ](https://echo.labstack.com/) 30 | - ✅ **Auth & Session middleware**: [Echo Contrib Session](https://github.com/labstack/echo-contrib/) 31 | - ✅ **Dependency Injection**: [Fx - dependency injection system for Go](https://uber-go.github.io/fx/) 32 | - ✅ **Database**: [PostgreSQL](https://www.postgresql.org/) 33 | - ✅ **Styling**: [TailwindCSS + DaisyUI](https://tailwindcss.com) 34 | - ✅ **Frontend interactivity**: [Htmx + _Hyperscript](https://htmx.org/) 35 | - ✅ **Templating Language**: [Templ - build HTML with Go](https://templ.guide/) 36 | - ✅ **Popup Boxes (Alerts)**: [Sweetalert2 - responsive & customizable replacement for JavaScript\'s popup boxes](https://sweetalert2.github.io/) 37 | 38 |
39 | 40 | 41 | >***The use of [htmx](https://htmx.org/) allows behavior similar to that of a SPA, without page reloads when switching from one route to another or when making requests (via AJAX) to the backend. Likewise, the [_hyperscript](https://hyperscript.org/) library allows you to add some dynamic features to the frontend in a very easy way.*** 42 | 43 |
44 | 45 | 46 | >***In this application, instead of using the [html/template](https://pkg.go.dev/html/template) package (native Golang templates), we use the [a-h/templ](https://github.com/a-h/templ) library. This amazing library implements a templating language (very similar to JSX) that compiles to Go code. Templ will allow us to write code almost identical to Go (with expressions, control flow, if/else, for loops, etc.) and have autocompletion thanks to strong typing. This means that errors appear at compile time and any calls to these templates (which are compiled as Go functions) from the handlers side will always require the correct data, minimizing errors and thus increasing the security and speed of our coding.*** 47 | 48 | --- 49 | 50 | ## 🖼️ Screenshots: 51 | 52 |
53 |
54 | 
57 |
58 | 
61 |
62 | 
65 |
66 | 
69 |
70 |
71 |
72 | ---
73 |
74 | ## 📦 Project structure
75 |
76 | ```
77 | - assets
78 | |- css
79 | |- img
80 | - database
81 | - encryption
82 | - internal
83 | |- api
84 | |- dto
85 | |- entity
86 | |- model
87 | |- repository
88 | |- service
89 | - postgresdb_init
90 | - settings
91 | - timezone_conversion
92 | - views
93 | |- auth_views
94 | |- components
95 | |- errors_pages
96 | |- layout
97 | |- links_views
98 | ```
99 |
100 | Home & Login Pages with success alert:
55 | 56 |
57 |
58 | Short link creator Page and Dashboard Page with alerts:
59 | 60 |
61 |
62 | Dashboard Page with alert and Short Link Update Modal:
63 | 64 |
65 |
66 | Centralized HTTP error handling:
67 | 68 |
69 |
70 | 101 | 102 |
103 |
104 | 105 | 106 | 107 | >***In this application, we have tried to apply a [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) pattern. The architecture follows a typical "onion model" where each layer doesn\'t know about the layer above it, and each layer is responsible for a specific thing. Although the application is extremely simple, we use this pattern to illustrate its use in more complex applications. Layering an application in this way can simplify code structure, since the responsibility of each type is clear. To ensure that each part of the application is initialized with its dependencies, each struct defines a constructor (the New function in this example). Related to the latter, we have used a dependency injector ([Fx](https://uber-go.github.io/fx/) from uber-go), which helps to remove the global state in the application and add new components and have them instantly accessible across the application.*** 108 | 109 |
110 | 111 | >***When applying this approach in a real-life application, as with most things, taking the layering approach to an extreme level can have a negative effect. Ask yourself if what you are doing actually helps make the code understandable or simply spreads the application logic across many files and makes the overall structure difficult to see.*** 112 | 113 | 114 | ## 👨🚀 Getting Started 115 | 116 | Besides the obvious prerequisite of having Go! on your machine, you must have Air installed for hot reloading when editing code. 117 | 118 | Since we use the PostgreSQL database from a Docker container, it is necessary to have the latter also installed and execute this command in the project folder: 119 | 120 | ``` 121 | $ docker compose up -d 122 | ``` 123 | 124 | These other commands will also be useful to manage the database from its container: 125 | 126 | ``` 127 | $ docker container start shortify-db # start container 128 | $ docker container stop shortify-db # stop container 129 | $ docker exec -it shortify-db psql -U admin -W shortify_db # (pass: admin) access the database 130 | ``` 131 | 132 | Download the necessary dependencies: 133 | 134 | ``` 135 | $ go mod tidy 136 | ``` 137 | 138 | Start the app in development mode: 139 | 140 | ``` 141 | $ air # Ctrl + C to stop the application 142 | ``` 143 | 144 | Build for production: 145 | 146 | ``` 147 | $ go build -ldflags="-s -w" -o ./bin/main . # ./bin/main to run the application / Ctrl + C to stop the application 148 | ``` 149 | 150 | 151 | >***In order to have autocompletion and syntax highlighting in VS Code for the Teml templating language, you will have to install the [templ-vscode](https://marketplace.visualstudio.com/items?itemName=a-h.templ) extension (for vim/nvim install this [plugin](https://github.com/joerdav/templ.vim)). To generate the Go code corresponding to these templates you will have to download this [executable binary](https://github.com/a-h/templ/releases/tag/v0.2.476) from Github and place it in the PATH of your system. The command:*** 152 | 153 | ``` 154 | $ templ generate --watch 155 | ``` 156 | 157 | >***This will allow us to monitor changes to the .templ files and compile them as we save them. Review the documentation on Templ [installation](https://templ.guide/quick-start/installation) and [support](https://templ.guide/commands-and-tools/ide-support/) for your IDE.*** 158 | 159 | --- 160 | 161 | ### Happy coding 😀!!', 162 | 'Example post of markdown rendering with its own syntax from the GitHub README.md file.' 163 | ); 164 | -- +goose StatementEnd 165 | 166 | -- +goose Down 167 | -- +goose StatementBegin 168 | DELETE FROM posts ORDER BY id DESC LIMIT 1; 169 | -- +goose StatementEnd 170 | -------------------------------------------------------------------------------- /assets/css/simple.min.css: -------------------------------------------------------------------------------- 1 | ::backdrop,:root{--sans-font:-apple-system,BlinkMacSystemFont,"Avenir Next",Avenir,"Nimbus Sans L",Roboto,"Noto Sans","Segoe UI",Arial,Helvetica,"Helvetica Neue",sans-serif;--mono-font:Consolas,Menlo,Monaco,"Andale Mono","Ubuntu Mono",monospace;--standard-border-radius:5px;--bg:#fff;--accent-bg:#f5f7ff;--text:#212121;--text-light:#585858;--border:#898EA4;--accent:#0d47a1;--accent-hover:#1266e2;--accent-text:var(--bg);--code:#d81b60;--preformatted:#444;--marked:#ffdd33;--disabled:#efefef}@media (prefers-color-scheme:dark){::backdrop,:root{color-scheme:dark;--bg:#212121;--accent-bg:#2b2b2b;--text:#dcdcdc;--text-light:#ababab;--accent:#ffb300;--accent-hover:#ffe099;--accent-text:var(--bg);--code:#f06292;--preformatted:#ccc;--disabled:#111}img,video{opacity:.8}}*,::after,::before{box-sizing:border-box}input,progress,select,textarea{appearance:none;-webkit-appearance:none;-moz-appearance:none}html{font-family:var(--sans-font);scroll-behavior:smooth}body{color:var(--text);background-color:var(--bg);font-size:1.15rem;line-height:1.5;display:grid;grid-template-columns:1fr min(45rem,90%) 1fr;margin:0}body>*{grid-column:2}body>header{background-color:var(--accent-bg);border-bottom:1px solid var(--border);text-align:center;padding:0 .5rem 2rem .5rem;grid-column:1/-1}body>header>:only-child{margin-block-start:2rem}body>header h1{max-width:1200px;margin:1rem auto}body>header p{max-width:40rem;margin:1rem auto}main{padding-top:1.5rem}body>footer{margin-top:4rem;padding:2rem 1rem 1.5rem 1rem;color:var(--text-light);font-size:.9rem;text-align:center;border-top:1px solid var(--border)}h1{font-size:3rem}h2{font-size:2.6rem;margin-top:3rem}h3{font-size:2rem;margin-top:3rem}h4{font-size:1.44rem}h5{font-size:1.15rem}h6{font-size:.96rem}p{margin:1.5rem 0}h1,h2,h3,h4,h5,h6,p{overflow-wrap:break-word}h1,h2,h3{line-height:1.1}@media only screen and (max-width:720px){h1{font-size:2.5rem}h2{font-size:2.1rem}h3{font-size:1.75rem}h4{font-size:1.25rem}}a,a:visited{color:var(--accent)}a:hover{text-decoration:none}.button,a.button,button,input[type=button],input[type=reset],input[type=submit],label[type=button]{border:1px solid var(--accent);background-color:var(--accent);color:var(--accent-text);padding:.5rem .9rem;text-decoration:none;line-height:normal}.button[aria-disabled=true],button[disabled],input:disabled,select:disabled,textarea:disabled{cursor:not-allowed;background-color:var(--disabled);border-color:var(--disabled);color:var(--text-light)}input[type=range]{padding:0}abbr[title]{cursor:help;text-decoration-line:underline;text-decoration-style:dotted}.button:not([aria-disabled=true]):hover,button:enabled:hover,input[type=button]:enabled:hover,input[type=reset]:enabled:hover,input[type=submit]:enabled:hover,label[type=button]:hover{background-color:var(--accent-hover);border-color:var(--accent-hover);cursor:pointer}.button:focus-visible,button:focus-visible:where(:enabled),input:enabled:focus-visible:where([type=submit],[type=reset],[type=button]){outline:2px solid var(--accent);outline-offset:1px}header>nav{font-size:1rem;line-height:2;padding:1rem 0 0 0}header>nav ol,header>nav ul{align-content:space-around;align-items:center;display:flex;flex-direction:row;flex-wrap:wrap;justify-content:center;list-style-type:none;margin:0;padding:0}header>nav ol li,header>nav ul li{display:inline-block}header>nav a,header>nav a:visited{margin:0 .5rem 1rem .5rem;border:1px solid var(--border);border-radius:var(--standard-border-radius);color:var(--text);display:inline-block;padding:.1rem 1rem;text-decoration:none}header>nav a.current,header>nav a:hover,header>nav a[aria-current=page]{border-color:var(--accent);color:var(--accent);cursor:pointer}@media only screen and (max-width:720px){header>nav a{border:none;padding:0;text-decoration:underline;line-height:1}}aside,details,pre,progress{background-color:var(--accent-bg);border:1px solid var(--border);border-radius:var(--standard-border-radius);margin-bottom:1rem}aside{font-size:1rem;width:30%;padding:0 15px;margin-inline-start:15px;float:right}[dir=rtl] aside{float:left}@media only screen and (max-width:720px){aside{width:100%;float:none;margin-inline-start:0}}article,dialog,fieldset{border:1px solid var(--border);padding:1rem;border-radius:var(--standard-border-radius);margin-bottom:1rem}article h2:first-child,section h2:first-child{margin-top:1rem}section{border-top:1px solid var(--border);border-bottom:1px solid var(--border);padding:2rem 1rem;margin:3rem 0}section+section,section:first-child{border-top:0;padding-top:0}section:last-child{border-bottom:0;padding-bottom:0}details{padding:.7rem 1rem}summary{cursor:pointer;font-weight:700;padding:.7rem 1rem;margin:-.7rem -1rem;word-break:break-all}details[open]>summary+*{margin-top:0}details[open]>summary{margin-bottom:.5rem}details[open]>:last-child{margin-bottom:0}table{border-collapse:collapse;margin:1.5rem 0}figure>table{width:max-content}td,th{border:1px solid var(--border);text-align:start;padding:.5rem}th{background-color:var(--accent-bg);font-weight:700}tr:nth-child(even){background-color:var(--accent-bg)}table caption{font-weight:700;margin-bottom:.5rem}.button,button,input,select,textarea{font-size:inherit;font-family:inherit;padding:.5rem;margin-bottom:.5rem;border-radius:var(--standard-border-radius);box-shadow:none;max-width:100%;display:inline-block}input,select,textarea{color:var(--text);background-color:var(--bg);border:1px solid var(--border)}label{display:block}textarea:not([cols]){width:100%}select:not([multiple]){background-image:linear-gradient(45deg,transparent 49%,var(--text) 51%),linear-gradient(135deg,var(--text) 51%,transparent 49%);background-position:calc(100% - 15px),calc(100% - 10px);background-size:5px 5px,5px 5px;background-repeat:no-repeat;padding-inline-end:25px}[dir=rtl] select:not([multiple]){background-position:10px,15px}input[type=checkbox],input[type=radio]{vertical-align:middle;position:relative;width:min-content}input[type=checkbox]+label,input[type=radio]+label{display:inline-block}input[type=radio]{border-radius:100%}input[type=checkbox]:checked,input[type=radio]:checked{background-color:var(--accent)}input[type=checkbox]:checked::after{content:" ";width:.18em;height:.32em;border-radius:0;position:absolute;top:.05em;left:.17em;background-color:transparent;border-right:solid var(--bg) .08em;border-bottom:solid var(--bg) .08em;font-size:1.8em;transform:rotate(45deg)}input[type=radio]:checked::after{content:" ";width:.25em;height:.25em;border-radius:100%;position:absolute;top:.125em;background-color:var(--bg);left:.125em;font-size:32px}@media only screen and (max-width:720px){input,select,textarea{width:100%}}input[type=color]{height:2.5rem;padding:.2rem}input[type=file]{border:0}hr{border:none;height:1px;background:var(--border);margin:1rem auto}mark{padding:2px 5px;border-radius:var(--standard-border-radius);background-color:var(--marked);color:#000}mark a{color:#0d47a1}img,video{max-width:100%;height:auto;border-radius:var(--standard-border-radius)}figure{margin:0;display:block;overflow-x:auto}figcaption{text-align:center;font-size:.9rem;color:var(--text-light);margin-bottom:1rem}blockquote{margin-inline-start:2rem;margin-inline-end:0;margin-block:2rem;padding:.4rem .8rem;border-inline-start:.35rem solid var(--accent);color:var(--text-light);font-style:italic}cite{font-size:.9rem;color:var(--text-light);font-style:normal}dt{color:var(--text-light)}code,kbd,pre,pre span,samp{font-family:var(--mono-font);color:var(--code)}kbd{color:var(--preformatted);border:1px solid var(--preformatted);border-bottom:3px solid var(--preformatted);border-radius:var(--standard-border-radius);padding:.1rem .4rem}pre{padding:1rem 1.4rem;max-width:100%;overflow:auto;color:var(--preformatted)}pre code{color:var(--preformatted);background:0 0;margin:0;padding:0}progress{width:100%}progress:indeterminate{background-color:var(--accent-bg)}progress::-webkit-progress-bar{border-radius:var(--standard-border-radius);background-color:var(--accent-bg)}progress::-webkit-progress-value{border-radius:var(--standard-border-radius);background-color:var(--accent)}progress::-moz-progress-bar{border-radius:var(--standard-border-radius);background-color:var(--accent);transition-property:width;transition-duration:.3s}progress:indeterminate::-moz-progress-bar{background-color:var(--accent-bg)}dialog{max-width:40rem;margin:auto}dialog::backdrop{background-color:var(--bg);opacity:.8}@media only screen and (max-width:720px){dialog{max-width:100%;margin:auto 1em}}sub,sup{vertical-align:baseline;position:relative}sup{top:-.4em}sub{top:.3em}.notice{background:var(--accent-bg);border:2px solid var(--border);border-radius:var(--standard-border-radius);padding:1.5rem;margin:2rem 0} -------------------------------------------------------------------------------- /internal/admin_app/api/api .go: -------------------------------------------------------------------------------- 1 | package api 2 | 3 | import ( 4 | "fmt" 5 | "os" 6 | "regexp" 7 | "strings" 8 | 9 | "github.com/emarifer/gocms/internal/service" 10 | "github.com/emarifer/gocms/settings" 11 | "github.com/gin-contrib/gzip" 12 | "github.com/gin-gonic/gin" 13 | "github.com/go-playground/validator/v10" 14 | lua "github.com/yuin/gopher-lua" 15 | ) 16 | 17 | type API struct { 18 | serv service.Service 19 | dataValidator *validator.Validate 20 | settings *settings.AppSettings 21 | } 22 | 23 | type ErrorResponse struct { 24 | Field string `json:"field"` 25 | Tag string `json:"tag"` 26 | Value string `json:"value,omitempty"` 27 | } 28 | 29 | func New( 30 | serv service.Service, 31 | dataValidator *validator.Validate, 32 | settings *settings.AppSettings, 33 | ) *API { 34 | 35 | return &API{ 36 | serv: serv, 37 | dataValidator: dataValidator, 38 | settings: settings, 39 | } 40 | } 41 | 42 | var re = regexp.MustCompile(`Table|refused`) 43 | 44 | // Find all the occurences of {{ and }} (including whitespace) 45 | var shortcodesFound = regexp.MustCompile(`{{[\s\w.-]+(:[\s\w.-]+)+}}`) 46 | 47 | func (a *API) Start(e *gin.Engine, address string) (*gin.Engine, error) { 48 | e.Use(gzip.Gzip(gzip.DefaultCompression)) // gzip compression middleware 49 | e.Use(a.globalErrorHandler()) // Error handler middleware 50 | e.MaxMultipartMemory = 1 // 8 MiB max. request 51 | 52 | a.registerRoutes(e) 53 | 54 | // SEE NOTE BELOW (this is hacky): 55 | if os.Getenv("GO_ENV") == "testing" { 56 | 57 | return e, nil 58 | } else { 59 | 60 | return nil, e.Run(address) 61 | } 62 | } 63 | 64 | func (a *API) registerRoutes(e *gin.Engine) { 65 | v1 := e.Group("api/v1") 66 | v1.POST("/post", a.addPostHandler) 67 | v1.GET("/post", a.getPostsHandler) 68 | v1.GET("/post/:id", a.postHandler) 69 | v1.PUT("/post", a.updatePostHandler) 70 | v1.DELETE("/post/:id", a.deletePostHandler) 71 | 72 | v1.GET("/image/:uuid", a.getImageHandler) 73 | v1.GET("/image", a.getAllImagesHandler) 74 | v1.POST("image", a.addImageHandler) 75 | v1.DELETE("/image/:uuid", a.deleteImageHandler) 76 | 77 | /* e.GET("/contact", a.contactHandler) 78 | e.POST("/contact", a.contactHandler) */ 79 | } 80 | 81 | func (a *API) validateStruct(payload any) []ErrorResponse { // SEE NOTE BELOW 82 | var errors []ErrorResponse 83 | 84 | err := a.dataValidator.Struct(payload) 85 | if err != nil { 86 | for _, err := range err.(validator.ValidationErrors) { 87 | var element ErrorResponse 88 | element.Field = err.StructNamespace() 89 | element.Tag = err.Tag() 90 | element.Value = err.Param() 91 | errors = append(errors, element) 92 | } 93 | } 94 | 95 | return errors 96 | } 97 | 98 | func (a *API) loadShortcodeHandlers() (map[string]*lua.LState, error) { 99 | shortcodeHandlers := map[string]*lua.LState{} 100 | 101 | for _, shortcode := range a.settings.Shortcodes { 102 | // Read the LState (Lua state) 103 | state := lua.NewState() 104 | err := state.DoFile(shortcode.Plugin) 105 | // TODO : check that the function HandleShortcode(args) 106 | // exists and returns the correct type 107 | if err != nil { 108 | return shortcodeHandlers, fmt.Errorf( 109 | "could not load shortcode %s: %v", shortcode.Name, err, 110 | ) 111 | } 112 | shortcodeHandlers[shortcode.Name] = state 113 | } 114 | 115 | return shortcodeHandlers, nil 116 | } 117 | 118 | // partitionString will partition the strings by 119 | // removing the given ranges 120 | func (a *API) partitionString(text string, indexes [][]int) []string { 121 | partitions := []string{} 122 | start := 0 123 | 124 | for _, window := range indexes { 125 | partitions = append(partitions, text[start:window[0]]) 126 | start = window[1] 127 | } 128 | 129 | partitions = append(partitions, text[start:len(text)-1]) 130 | 131 | return partitions 132 | } 133 | 134 | func (a *API) shortcodeToMarkdown( 135 | shortcode string, shortcodeHandlers map[string]*lua.LState, 136 | ) (string, error) { 137 | keyValue := strings.Split(shortcode, ":") 138 | key := keyValue[0] 139 | values := keyValue[1:] 140 | 141 | /* if key == "img" { 142 | if len(values) == 1 { 143 | imageSrc := fmt.Sprintf("/media/%s", values[0]) 144 | 145 | return fmt.Sprintf("", imageSrc), nil 146 | } else if len(values) == 2 { 147 | imageSrc := fmt.Sprintf("/media/%s", values[0]) 148 | altText := values[1] 149 | 150 | return fmt.Sprintf("", altText, imageSrc), nil 151 | } else { 152 | return "", fmt.Errorf("invalid shortcode: %s", shortcode) 153 | } 154 | } */ 155 | 156 | if handler, found := shortcodeHandlers[key]; found { 157 | // Need to quote all values for a valid lua syntax 158 | quotedValues := []string{} 159 | for _, value := range values { 160 | quotedValues = append(quotedValues, fmt.Sprintf("%q", value)) 161 | } 162 | 163 | err := handler.DoString(fmt.Sprintf( 164 | `result = HandleShortcode({%s})`, strings.Join(quotedValues, ","), 165 | )) 166 | if err != nil { 167 | return "", fmt.Errorf("error running %s shortcode: %v", key, err) 168 | } 169 | 170 | value := handler.GetGlobal("result") 171 | if retType := value.Type().String(); retType != "string" { 172 | return "", fmt.Errorf( 173 | "error running %s shortcode: invalid return type %s", key, retType, 174 | ) 175 | } else if retType == "" { 176 | return "", fmt.Errorf( 177 | "error running %s shortcode: returned empty string", key, 178 | ) 179 | } 180 | 181 | return value.String(), nil 182 | } 183 | 184 | return "", fmt.Errorf("unsupported shortcode: %s", key) 185 | } 186 | 187 | func (a *API) transformContent( 188 | content string, shortcodeHandlers map[string]*lua.LState, 189 | ) (string, error) { 190 | // see note below 191 | shortcodes := shortcodesFound.FindAllStringIndex(content, -1) 192 | // content without shortcodes 193 | partitions := a.partitionString(content, shortcodes) 194 | 195 | builder := strings.Builder{} 196 | // i := 0 197 | for i, shortcode := range shortcodes { 198 | builder.WriteString(partitions[i]) 199 | 200 | // +2 is added, or -2 is regressed, due to the double curly brackets 201 | md, err := a.shortcodeToMarkdown( 202 | content[shortcode[0]+2:shortcode[1]-2], shortcodeHandlers, 203 | ) 204 | if err != nil { 205 | return "", fmt.Errorf("could not transform post: %v", err) 206 | } 207 | 208 | builder.WriteString(md) 209 | } 210 | 211 | // Guaranteed to have +1 than the number of 212 | // shortcodes by algorithm 213 | if len(shortcodes) > 0 { 214 | builder.WriteString(partitions[len(partitions)-1]) 215 | } else { 216 | builder.WriteString(content) 217 | } 218 | 219 | return builder.String(), nil 220 | } 221 | 222 | /* HOW DO I KNOW I'M RUNNING WITHIN "GO TEST". SEE: 223 | https://stackoverflow.com/questions/14249217/how-do-i-know-im-running-within-go-test#59444829 224 | */ 225 | 226 | /* 227 | // Markdown to HTML conversion 228 | func (a *API) mdToHTML(md []byte) []byte { 229 | // create markdown parser with extensions 230 | extensions := parser.CommonExtensions | parser.AutoHeadingIDs | parser.NoEmptyLineBeforeBlock 231 | p := parser.NewWithExtensions(extensions) 232 | doc := p.Parse(md) 233 | 234 | // create HTML renderer with extensions 235 | htmlFlags := html.CommonFlags | html.HrefTargetBlank 236 | opts := html.RendererOptions{Flags: htmlFlags} 237 | renderer := html.NewRenderer(opts) 238 | 239 | return markdown.Render(doc, renderer) 240 | } 241 | 242 | // This function will render the templ component into 243 | // a gin context's Response Writer 244 | func (a *API) renderView( 245 | c *gin.Context, status int, cmp templ.Component, 246 | ) error { 247 | c.Status(status) 248 | 249 | return cmp.Render(c.Request.Context(), c.Writer) 250 | } 251 | */ 252 | 253 | /* FINDING THE INDEX OF ALL OCCURRENCES OF A REGULAR EXPRESSION IN A STRING. SEE: 254 | https://www.tutorialspoint.com/finding-index-of-the-regular-expression-present-in-string-of-golang 255 | */ 256 | 257 | /* NO PARAMETERIZED METHODS. SEE: 258 | https://go.googlesource.com/proposal/+/refs/heads/master/design/43651-type-parameters.md#No-parameterized-methods 259 | 260 | JSON Escape / Unescape Online. SEE: 261 | https://www.freeformatter.com/json-escape.html#before-output 262 | 263 | What HTTP status code should I return for POST when no resource is created?. SEE: 264 | https://stackoverflow.com/questions/55685576/what-http-status-code-should-i-return-for-post-when-no-resource-is-created 265 | */ 266 | -------------------------------------------------------------------------------- /internal/admin_app/api/images.handlers.go: -------------------------------------------------------------------------------- 1 | package api 2 | 3 | import ( 4 | "fmt" 5 | "net/http" 6 | "os" 7 | "path/filepath" 8 | "slices" 9 | "strconv" 10 | "strings" 11 | 12 | "github.com/emarifer/gocms/internal/admin_app/api/dto" 13 | "github.com/emarifer/gocms/internal/entity" 14 | "github.com/gin-gonic/gin" 15 | "github.com/google/uuid" 16 | ) 17 | 18 | func (a *API) addImageHandler(c *gin.Context) { 19 | c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 10*1000000) 20 | ctx := c.Request.Context() 21 | 22 | mForm, err := c.MultipartForm() 23 | if err != nil { 24 | customError := NewCustomError( 25 | http.StatusInternalServerError, 26 | err.Error(), 27 | "could not create multipart form", 28 | ) 29 | c.Error(customError) 30 | 31 | return 32 | } 33 | 34 | alt_text_array := mForm.Value["alt"] 35 | alt_text := "unknown" 36 | if len(alt_text_array) > 0 { 37 | alt_text = alt_text_array[0] 38 | } 39 | 40 | /* addImageBinding := &dto.AddImageRequest{} 41 | 42 | if err := c.ShouldBind(addImageBinding); err != nil { 43 | customError := NewCustomError( 44 | http.StatusBadRequest, 45 | err.Error(), 46 | "invalid request body", 47 | ) 48 | c.Error(customError) 49 | 50 | return 51 | } 52 | 53 | alt_text := addImageBinding.Alt */ 54 | 55 | // Begin saving the file to the filesystem 56 | file_array := mForm.File["file"] 57 | if len(file_array) == 0 { 58 | customError := NewCustomError( 59 | http.StatusBadRequest, 60 | "error: could not get the file array", 61 | "could not get the file array", 62 | ) 63 | c.Error(customError) 64 | 65 | return 66 | } 67 | file := file_array[0] 68 | if file == nil { 69 | customError := NewCustomError( 70 | http.StatusBadRequest, 71 | "error: could not upload file", 72 | "could not upload file", 73 | ) 74 | c.Error(customError) 75 | 76 | return 77 | } 78 | allowed_types := []string{"image/jpeg", "image/png", "image/gif"} 79 | if file_content_type := file.Header.Get("content-type"); !slices.Contains( 80 | allowed_types, file_content_type, 81 | ) { 82 | customError := NewCustomError( 83 | http.StatusBadRequest, 84 | "error: file type not supported", 85 | "file type not supported", 86 | ) 87 | c.Error(customError) 88 | 89 | return 90 | } 91 | allowed_extensions := []string{".jpeg", ".jpg", ".png"} 92 | ext := filepath.Ext(file.Filename) 93 | // check ext is supported 94 | if ext != "" && !slices.Contains(allowed_extensions, ext) { 95 | customError := NewCustomError( 96 | http.StatusBadRequest, 97 | "error: file extension is not supported", 98 | "file extension is not supported", 99 | ) 100 | c.Error(customError) 101 | 102 | return 103 | } 104 | 105 | uuid := uuid.New() 106 | filename := fmt.Sprintf("%s%s", uuid.String(), ext) 107 | // rootPath, _ := os.Getwd() 108 | image_path := filepath.Join( 109 | a.settings.ImageDirectory, filename, 110 | ) 111 | err = c.SaveUploadedFile(file, image_path) 112 | if err != nil { 113 | customError := NewCustomError( 114 | http.StatusInternalServerError, 115 | err.Error(), 116 | "could not save file", 117 | ) 118 | c.Error(customError) 119 | 120 | return 121 | } 122 | // End saving to filesystem 123 | 124 | // Save metadata into the DB 125 | imageData := &entity.Image{ 126 | UUID: uuid, 127 | Name: filename, 128 | Alt: alt_text, 129 | } 130 | 131 | err = a.serv.CreateImageMetadata(ctx, imageData) 132 | if err != nil { 133 | customError := NewCustomError( 134 | http.StatusInternalServerError, 135 | err.Error(), 136 | "could not add image metadata to db", 137 | ) 138 | c.Error(customError) 139 | 140 | err = os.Remove(image_path) 141 | if err != nil { 142 | customError := NewCustomError( 143 | http.StatusInternalServerError, 144 | err.Error(), 145 | "could not remove image", 146 | ) 147 | c.Error(customError) 148 | } 149 | 150 | return 151 | } 152 | 153 | c.JSON(http.StatusCreated, gin.H{ 154 | "uuid": uuid.String(), 155 | }) 156 | } 157 | 158 | func (a *API) getImageHandler(c *gin.Context) { 159 | ctx := c.Request.Context() 160 | imageBinding := &dto.ImageBinding{} 161 | 162 | // localhost:8080/image/{uuid} 163 | if err := c.ShouldBindUri(imageBinding); err != nil { 164 | customError := NewCustomError( 165 | http.StatusBadRequest, 166 | err.Error(), 167 | "could not get image uuid", 168 | ) 169 | c.Error(customError) 170 | 171 | return 172 | } 173 | 174 | // Get image metadata by UUID 175 | 176 | imageMetadata, err := a.serv.RecoverImageMetadata(ctx, imageBinding.UUID) 177 | if err != nil { 178 | if re.MatchString(err.Error()) { 179 | customError := NewCustomError( 180 | http.StatusInternalServerError, 181 | err.Error(), 182 | "An unexpected condition was encountered.", 183 | ) 184 | c.Error(customError) 185 | 186 | return 187 | } 188 | 189 | if strings.Contains(err.Error(), "no rows in result set") { 190 | customError := NewCustomError( 191 | http.StatusNotFound, 192 | err.Error(), 193 | "The requested resource could not be found but may be available again in the future.", 194 | ) 195 | c.Error(customError) 196 | 197 | return 198 | } 199 | } 200 | 201 | c.JSON(http.StatusOK, gin.H{ 202 | "uuid": imageMetadata.UUID, 203 | "name": imageMetadata.Name, 204 | "alt": imageMetadata.Alt, 205 | }) 206 | } 207 | 208 | func (a *API) getAllImagesHandler(c *gin.Context) { 209 | var ( 210 | limit int 211 | err error 212 | ) 213 | ctx := c.Request.Context() 214 | limitStr := c.Query("limit") 215 | 216 | if limitStr == "" { 217 | limit = 5 218 | } else { 219 | limit, err = strconv.Atoi(limitStr) 220 | if err != nil { 221 | customError := NewCustomError( 222 | http.StatusBadRequest, 223 | err.Error(), 224 | "images limit type invalid", 225 | ) 226 | c.Error(customError) 227 | 228 | return 229 | } 230 | 231 | if limit == 0 { 232 | limit = 5 233 | } 234 | } 235 | 236 | ii, err := a.serv.RecoverAllImageMetadata(ctx, limit) 237 | if err != nil { 238 | if re.MatchString(err.Error()) { 239 | customError := NewCustomError( 240 | http.StatusInternalServerError, 241 | err.Error(), 242 | "An unexpected condition was encountered.", 243 | ) 244 | c.Error(customError) 245 | 246 | return 247 | } 248 | } 249 | 250 | c.JSON(http.StatusOK, gin.H{ 251 | "imageMetadata": ii, 252 | }) 253 | } 254 | 255 | func (a *API) deleteImageHandler(c *gin.Context) { 256 | ctx := c.Request.Context() 257 | imageBinding := &dto.ImageBinding{} 258 | 259 | // localhost:8080/image/{uuid} 260 | if err := c.ShouldBindUri(imageBinding); err != nil { 261 | customError := NewCustomError( 262 | http.StatusBadRequest, 263 | err.Error(), 264 | "could not get image uuid", 265 | ) 266 | c.Error(customError) 267 | 268 | return 269 | } 270 | 271 | // Get image metadata by UUID 272 | 273 | imageMetadata, err := a.serv.RecoverImageMetadata(ctx, imageBinding.UUID) 274 | if err != nil { 275 | if re.MatchString(err.Error()) { 276 | customError := NewCustomError( 277 | http.StatusInternalServerError, 278 | err.Error(), 279 | "An unexpected condition was encountered.", 280 | ) 281 | c.Error(customError) 282 | 283 | return 284 | } 285 | 286 | if strings.Contains(err.Error(), "no rows in result set") { 287 | customError := NewCustomError( 288 | http.StatusNotFound, 289 | err.Error(), 290 | "The requested resource could not be found but may be available again in the future.", 291 | ) 292 | c.Error(customError) 293 | 294 | return 295 | } 296 | } 297 | 298 | // Remove image metadata by uuid 299 | 300 | rowsAffected, err := a.serv.RemoveImage(ctx, imageBinding.UUID) 301 | if err != nil { 302 | if re.MatchString(err.Error()) { 303 | customError := NewCustomError( 304 | http.StatusInternalServerError, 305 | err.Error(), 306 | "An unexpected condition was encountered", 307 | ) 308 | c.Error(customError) 309 | 310 | return 311 | } 312 | } 313 | 314 | if rowsAffected == -1 { 315 | customError := NewCustomError( 316 | http.StatusNotFound, 317 | "no rows in result set", 318 | "could not delete image metadata", 319 | ) 320 | c.Error(customError) 321 | 322 | return 323 | } 324 | 325 | // Delete file system image by its path 326 | // rootPath, _ := os.Getwd() 327 | image_path := filepath.Join( 328 | a.settings.ImageDirectory, imageMetadata.Name, 329 | ) 330 | err = os.Remove(image_path) 331 | if err != nil { 332 | customError := NewCustomError( 333 | http.StatusInternalServerError, 334 | err.Error(), 335 | "could not remove image file", 336 | ) 337 | c.Error(customError) 338 | 339 | return 340 | } 341 | 342 | c.JSON(http.StatusOK, gin.H{ 343 | "rowsAffected": rowsAffected, 344 | }) 345 | } 346 | 347 | /* REFERENCES: 348 | https://www.freeformatter.com/json-escape.html#before-output 349 | https://www.youtube.com/watch?v=yqDYYjbatfE 350 | https://github.com/sikozonpc/fullstack-go-htmx 351 | https://stackoverflow.com/questions/9722603/storing-image-in-database-directly-or-as-base64-data 352 | 353 | https://tutorialedge.net/golang/go-file-upload-tutorial/ 354 | 355 | https://www.google.com/search?q=golang+file+upload+rest+api&sca_esv=dcb7b8806130e33c&sxsrf=ACQVn08616pDvbQ3cGeZyya8IskU-hxACA%3A1709290929268&ei=sbXhZezxD4yX9u8Ps6CtuAI&oq=golang+file+u&gs_lp=Egxnd3Mtd2l6LXNlcnAiDWdvbGFuZyBmaWxlIHUqAggBMgwQIxiABBiKBRgTGCcyCBAAGIAEGMsBMggQABiABBjLATIIEAAYgAQYywEyCBAAGIAEGMsBMggQABiABBjLATIGEAAYFhgeMgYQABgWGB4yBhAAGBYYHjIGEAAYFhgeSPVIUNkMWKsScAF4AZABAJgBqAGgAcYEqgEDMi4zuAEByAEA-AEBmAIGoAL8BMICChAAGEcY1gQYsAOYAwCIBgGQBgiSBwMyLjQ&sclient=gws-wiz-serp 356 | */ 357 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 |
3 | 
6 |
7 |
8 | 9 |
18 |
19 | goCMS
4 | 5 |
6 |
7 | 8 | 9 |
10 | 11 | goCMS is a headless CMS (Content Management System) written in Golang using Gin framework + Htmx & A-H Templ, designed to be fast, efficient, and easily extensible. It allows you to create a website or blog, with any template you like, in only a few commands. 12 | 13 |
14 | 15 |   16 | 17 |20 | 21 | ## Features 🚀 22 | 23 | - [x] **Headless Architecture:** Adding pages, posts, or forms should all 24 | be done with easy requests to the API. 25 | - [x] **Golang-Powered:** Leverage the performance and safety of one of the 26 | best languages in the market for backend development. 27 | - [x] **SQL Database Integration:** Store your posts and pages in SQL databases for reliable and scalable data storage. 28 | - [x] **Centralized HTTP error handling:** The user receives feedback about the Http errors that their actions may cause, through the use of middleware that centralizes the Http errors that occur. 29 | - [x] **Caching HTML responses from endpoints:** Own implementation of an in-memory cache that stores HTML responses for 10 minutes in a map with mutex lock R/W access. 30 | - [x] **Live Reload:** through the use of `air`. 31 | - [x] **Possibility for the user to add their own plugins written in `Lua`:** this feature allows you to customize the admin application at runtime. 32 | - [ ] **Post**: We can add, update, and delete posts. Posts can be served 33 | through a unique URL. 34 | - [ ] **Pages**: TODO. 35 | - [ ] **Menus**: TODO 36 | 37 |
38 | 39 | >[!IMPORTANT] 40 | >***The Go language uses [html/template](https://pkg.go.dev/html/template) package to render HTML. In this application we have used the [a-h/templ](https://github.com/a-h/templ) library instead. The main difference is that templ uses a generation step to compile the files .templ into Go code (as functions). This means that the templates are type-safe and can be checked at compile time. This amazing library implements a templating language (very similar to JSX) which allows you to write code almost identical to Go (with expressions, control flow, if/else, for loops, etc.) and have autocompletion. For all these reasons, calling these templates from the controllers side will always require the correct data, minimizing errors and thus increasing the security and speed of our coding.*** 41 | 42 | ## Installation 43 | 44 | Ensure you have Golang installed on your system before proceeding with the installation. 45 | 46 | ```bash 47 | go get -u github.com/emarifer/gocms 48 | ``` 49 | 50 | ### Example - Running the App (user application) manually 51 | 52 | First, make sure you have the necessary executable binaries to run and work with the application. 53 | 54 | ```bash 55 | make install-tools 56 | ``` 57 | 58 | After that, with the `MariaDB` database engine running, with the idea of populating the database with some sample data, make sure to run the migrations with the previously installed `Goose` tool. We recommend creating a database called `cms_db` and running the following command: 59 | 60 | ```bash 61 | GOOSE_DRIVER="mysql" GOOSE_DBSTRING="root:root@/cms_db" goose up 62 | ``` 63 | Replace the database connection string with the appropriate string 64 | dependending on where your database is. 65 | 66 | After you've replaced the default template files with your prefered 67 | template, simply build and start the app with the following commands. 68 | 69 | ```bash 70 | go mod tidy && go build -ldflags="-s -w" -v -o ./tmp/gocms ./cmd/gocms && ./tmp/gocms 71 | ``` 72 | 73 | Alternatively, the `air` command will allow us to start the user application (also creating the admin application executable), having, however, with said command the possibility of hot reloading after any change in the user/admin applications code. 74 | 75 | This will start `goCMS` on `http://localhost:8080`. If we have used the `air` command we can start the admin application with the `make run` (on `http://localhost:8081`) command. You can customize the configuration by providing the necessary environment variables. 76 | 77 | ```bash 78 | # e.g. 79 | 80 | DATABASE_PORT=3306 ./tmp/gocms-admin 81 | ``` 82 | 83 | For more information, see the [configuration settings](#configuration). 84 | 85 | ### Example - Running with Docker Compose (user & admin applications) 86 | 87 | In this case the only requirement is to have `Docker` installed and running. 88 | 89 | To create the image and the `Docker` containers and start the application you only need to run the following command in the project folder: 90 | 91 | ```bash 92 | make run-containers 93 | ``` 94 | The above will create an Ubuntu:jammy image and, within that OS, will install Golang, Goose, A-H.Templ and Air. Next, from said image and the mariadb:jammy image, you will create and start two containers: one containing the `goCMS` app, serving on port `8080`, and another one serving the `mariadb` database internally. This will also run the migrations automatically to setup the database! 95 | 96 | To stop and eliminate both containers we will execute the following in another terminal: 97 | 98 | ```bash 99 | docker compose down # to stop and remove containers (run in another terminal) 100 | ``` 101 | 102 | If we do not plan to delete the containers with the idea of continuing to reuse them, we will simply press `Ctrl+C` in the same terminal. This will stop the containers without deleting them. The next time we want to start the application we will run `make run-containers` again. 103 | 104 | As long as we have created/run the aforementioned containers, the management application executable file will have been created. To start it (within `Docker`), simply run the following commands: 105 | 106 | ```bash 107 | docker exec -it docker-gocms-1 sh # to enter the `docker-gocms-1` container 108 | 109 | cd gocms && make start-admin-container # to enter the project folder (inside the container) and start the admin application 110 | ``` 111 | 112 | >[!NOTE] 113 | >***the above serves the application in `http://localhost:8081`.*** 114 | 115 | ## Architecture 116 | 117 | Currently, the architecture of `goCMS` is still in its early days. 118 | The plan is to have two main applications: the public facing application 119 | to serve the content through a website, and the admin application that 120 | can be hidden, where users can modify the settings, add posts, pages, etc. 121 | 122 | ## Configuration 123 | 124 | The runtime configuration can be done through a [toml](https://toml.io/en/) configuration file or by setting the mandatory environment variables (*fallback*). This approach was chosen because configuration via toml supports advanced features (i.e. *relationships*, *arrays*, etc.). The `.dev.env`-file used only for the `goose up` command, they are not needed for `Docker` files. 125 | 126 | ### `.toml` configuration 127 | 128 | The application can be started by providing the `config` flag which has to be set to a toml configuration file. The file has to contain the following mandatory values: 129 | 130 | ```toml 131 | webserver_port = 8080 # port to run the webserver on 132 | admin_webserver_port = 8081 # port to run the webserver (admin) on 133 | database_host = "localhost" # database host (address to the MariaDB database) 134 | database_port = 3306 # database port 135 | database_user = "root" # database user 136 | database_password = "my-secret-pw" # database password 137 | database_name = "cms_db" # name of the database that is created through `Docker` 138 | image_dir = "./media" # directory to use for storing uploaded images 139 | 140 | # optional: directives containing the name and path of user-supplied `Lua` plugins 141 | # e.g. 142 | 143 | [[shortcodes]] 144 | name = "img" 145 | # must have function "HandleShortcode(arguments []string) -> string" 146 | plugin = "plugins/image_shortcode.lua" 147 | ``` 148 | 149 | >[!NOTE] 150 | >***The above configuration values are used to start the local development database, in addition to the user/admin application ports, media storage folder, or optionally, admin plugins directives.*** 151 | 152 | ### Environment variables configuration (fallback) 153 | 154 | If chosen, by setting the following environment variables the application can be started without providing a toml configuration file (although a file of this type is necessary to establish the directives of user plugins written in `Lua`). 155 | 156 | - `WEBSERVER_PORT` port the application should run on 157 | - `ADMIN_WEBSERVER_PORT` the same as the previous one but for the admin app 158 | - `DATABASE_HOST` should contain the database addres, e.g. `localhost` 159 | - `DATABASE_PORT` should be the connection port to the db, e.g. `3306` 160 | - `DATABASE_USER` is the database username. 161 | - `DATABASE_PASSWORD` needs to contain the database password for the given user. 162 | - `DATABASE_NAME` sets the name of the database `goCMS` will use. 163 | - `IMAGE_DIRECTORY` directory images should be stored to if uploaded to `goCMS` 164 | 165 | To the above (as we have already mentioned), we would have to add an environment variable (`CONFIG_FILE_PATH`) that contains the path to a `.toml` file that contains the directives for the plugins (`Lua` scripts) that the user wants add. This file would have the form: 166 | 167 | ```toml 168 | # e.g. 169 | 170 | [[shortcodes]] 171 | name = "img" 172 | # must have function "HandleShortcode(arguments []string) -> string" 173 | plugin = "plugins/image_shortcode.lua" 174 | ``` 175 | 176 | ## Development 177 | 178 | To facilitate the development process, `Docker` is highly recommended. This way you can use `docker/mariadb.yml` to configure a predefined MariaDB database server. The file `mariadb.yml` creates the database `cms_db`. 179 | 180 | ```bash 181 | $ make start-devdb 182 | ``` 183 | 184 | To populate the aforementioned db with some sample data you can use this command: 185 | 186 | ```bash 187 | $ make run-migrations 188 | ``` 189 | 190 | ## License 191 | 192 | `goCMS` is released under the MIT License. See LICENSE for 193 | details. Feel free to fork, modify, and use it in your projects! 194 | 195 | --- 196 | 197 | ## Happy coding 😀!! -------------------------------------------------------------------------------- /assets/js/htmx.min.js: -------------------------------------------------------------------------------- 1 | (function(e,t){if(typeof define==="function"&&define.amd){define([],t)}else if(typeof module==="object"&&module.exports){module.exports=t()}else{e.htmx=e.htmx||t()}})(typeof self!=="undefined"?self:this,function(){return function(){"use strict";var Q={onLoad:F,process:zt,on:de,off:ge,trigger:ce,ajax:Nr,find:C,findAll:f,closest:v,values:function(e,t){var r=dr(e,t||"post");return r.values},remove:_,addClass:z,removeClass:n,toggleClass:$,takeClass:W,defineExtension:Ur,removeExtension:Br,logAll:V,logNone:j,logger:null,config:{historyEnabled:true,historyCacheSize:10,refreshOnHistoryMiss:false,defaultSwapStyle:"innerHTML",defaultSwapDelay:0,defaultSettleDelay:20,includeIndicatorStyles:true,indicatorClass:"htmx-indicator",requestClass:"htmx-request",addedClass:"htmx-added",settlingClass:"htmx-settling",swappingClass:"htmx-swapping",allowEval:true,allowScriptTags:true,inlineScriptNonce:"",attributesToSettle:["class","style","width","height"],withCredentials:false,timeout:0,wsReconnectDelay:"full-jitter",wsBinaryType:"blob",disableSelector:"[hx-disable], [data-hx-disable]",useTemplateFragments:false,scrollBehavior:"smooth",defaultFocusScroll:false,getCacheBusterParam:false,globalViewTransitions:false,methodsThatUseUrlParams:["get"],selfRequestsOnly:false,ignoreTitle:false,scrollIntoViewOnBoost:true,triggerSpecsCache:null},parseInterval:d,_:t,createEventSource:function(e){return new EventSource(e,{withCredentials:true})},createWebSocket:function(e){var t=new WebSocket(e,[]);t.binaryType=Q.config.wsBinaryType;return t},version:"1.9.10"};var r={addTriggerHandler:Lt,bodyContains:se,canAccessLocalStorage:U,findThisElement:xe,filterValues:yr,hasAttribute:o,getAttributeValue:te,getClosestAttributeValue:ne,getClosestMatch:c,getExpressionVars:Hr,getHeaders:xr,getInputValues:dr,getInternalData:ae,getSwapSpecification:wr,getTriggerSpecs:it,getTarget:ye,makeFragment:l,mergeObjects:le,makeSettleInfo:T,oobSwap:Ee,querySelectorExt:ue,selectAndSwap:je,settleImmediately:nr,shouldCancel:ut,triggerEvent:ce,triggerErrorEvent:fe,withExtensions:R};var w=["get","post","put","delete","patch"];var i=w.map(function(e){return"[hx-"+e+"], [data-hx-"+e+"]"}).join(", ");var S=e("head"),q=e("title"),H=e("svg",true);function e(e,t=false){return new RegExp(`<${e}(\\s[^>]*>|>)([\\s\\S]*?)<\\/${e}>`,t?"gim":"im")}function d(e){if(e==undefined){return undefined}let t=NaN;if(e.slice(-2)=="ms"){t=parseFloat(e.slice(0,-2))}else if(e.slice(-1)=="s"){t=parseFloat(e.slice(0,-1))*1e3}else if(e.slice(-1)=="m"){t=parseFloat(e.slice(0,-1))*1e3*60}else{t=parseFloat(e)}return isNaN(t)?undefined:t}function ee(e,t){return e.getAttribute&&e.getAttribute(t)}function o(e,t){return e.hasAttribute&&(e.hasAttribute(t)||e.hasAttribute("data-"+t))}function te(e,t){return ee(e,t)||ee(e,"data-"+t)}function u(e){return e.parentElement}function re(){return document}function c(e,t){while(e&&!t(e)){e=u(e)}return e?e:null}function L(e,t,r){var n=te(t,r);var i=te(t,"hx-disinherit");if(e!==t&&i&&(i==="*"||i.split(" ").indexOf(r)>=0)){return"unset"}else{return n}}function ne(t,r){var n=null;c(t,function(e){return n=L(t,e,r)});if(n!=="unset"){return n}}function h(e,t){var r=e.matches||e.matchesSelector||e.msMatchesSelector||e.mozMatchesSelector||e.webkitMatchesSelector||e.oMatchesSelector;return r&&r.call(e,t)}function A(e){var t=/<([a-z][^\/\0>\x20\t\r\n\f]*)/i;var r=t.exec(e);if(r){return r[1].toLowerCase()}else{return""}}function a(e,t){var r=new DOMParser;var n=r.parseFromString(e,"text/html");var i=n.body;while(t>0){t--;i=i.firstChild}if(i==null){i=re().createDocumentFragment()}return i}function N(e){return/"+n+"",0);return i.querySelector("template").content}switch(r){case"thead":case"tbody":case"tfoot":case"colgroup":case"caption":return a("
"+n+"
",1);default:return a(n,0)}}function ie(e){if(e){e()}}function I(e,t){return Object.prototype.toString.call(e)==="[object "+t+"]"}function k(e){return I(e,"Function")}function P(e){return I(e,"Object")}function ae(e){var t="htmx-internal-data";var r=e[t];if(!r){r=e[t]={}}return r}function M(e){var t=[];if(e){for(var r=0;r