Ana içeriğe geç

GMUPOS Kurulum

GMU POS projesinin ihtiyaç duyduğu bileşenler:

- Uygulama .Net 8 kullanmaktadır.
- Sql Server 2019+ (Proje tabloları için)
- Sql Server 2019+ (Hangfire tabloları için)
- ELK (APM'li) bakınız : https://www.elastic.co/
- AuthServer (Default olarak Keycloak kullanılmaktadır.)
- Envoy (Gateway, opsiyonel, envoy zorunluluğu kalktı ve nginx/haproxy gibi alternatif reverse proxyler de kullanılabilir)
- Redis. İçerdiği veri gmu açısından kıymetsiz keşleme verisidir, tüm veri kaybedilse de gmu ektilenmez. Redis üzerinde tutulan keşleme verilerinde hassas veriler kriptolu olarak redise yazılmaktadır veya hassas verinin hash'i yazılmaktadır.
- GMU API (Tek taraflı GMU tarafına entegre bir sistem olduğu için GMU bağlantıları zorunludur.)
- Api'ye kolay erişim için herhangi bir domain üzerinde subdomain açılması (dns kaydı girilerek) önerilir. Benzer şekilde gmu-pos backoffice için de 2.bir subdomain açılması önerilir.

İhtiyaç duyulan tüm environment variable değerleri aşağıda verilmiştir. Zorunlu değer olanların başında '*' ibaresi vardır.

* ASPNETCORE_ENVIRONMENT=Development || Test || Staging || Production (Ortam bilgisini verir)
* ASPNETCORE_URLS=https://+:443;http://+:80 ()
* Auth__Issuer=${GMUPOS_AUTHSERVICE_URL_EXTERNAL}/realms/gmupos ()
- Auth__MetadataAddress=
* Auth__Audiences__0= Sistemin beklediği Audiences değerlerinden birisi değişiklik göstermez
* Auth__Audiences__1=Sistemin beklediği Audiences değerlerininde birisi değişiklik göstermez
- Serilog__WriteTo__0__Name=Loglamanın nereye yapılacağını belirtir
- Serilog__WriteTo__0__Args__nodeUris=Loglamanın yapılacağı yerin adresidir.
- Serilog__WriteTo__0__Args__indexFormat=gmupos_api-{0:yyyy.MM.dd} (Loglama yapılırken verilen index)
- Serilog__WriteTo__0__Args__autoRegisterTemplate=true
- Serilog__WriteTo__Elasticsearch__templateName=serilog-events-template 
- ElasticApm__ServerUrls=ELK APM için gerekli olan veri ';' ile ayırarak çoklu şekilde yazılabilir
- ElasticApm__ServiceName=ELK ortamını kimin beslediğini gösteren veri
- ElasticApm__Environment=dev (ELK ortamının Environment verisi)
- ElasticApm__ELKApiKey=
- ElasticIndex__Aliases=
- ElasticApm__UserName=
- ElasticApm__Password=
* Db__Main__ConnetionStringTemplate=Server=sqldata;Database=gmupos;User Id=sa;Password={0} (Projenin ana tablolarının yer alacağı veri tabanı bağlantı verisi)
* Db__Main__Password=Pass@word (Projenin ana tablolarının yer alacağı veri tabanı şifresi Secret üzerinden bu veri getirilirse daha sağlıklı olur)
* Db__Hangfire__ConnectionStringTemplate=Server=sqldata;Database=gmupos_hangfire;User Id=sa;Password={0} (Hangfire erişimi için istenilen bağlantı verisi)
* Db__Hangfire__Password=Pass@word (Hangfire erişimi için istenilen veri tabanı şifresi Secret üzerinden bu veri getirilirse daha sağlıklı olur)
* Gmu__EndpointUrl=https://gmu-apidevelopment.protel.com.tr/integrationapi/v2 (GMU Entegrasyonu için ortam bazlı değişkenlik gösteren GMU base url bilgisi)
* Gmu__AccessCredential__Username= GMU Entegrasyonu için ortam bazlı değişkenlik gösteren GMU kullanıcı adı
* Gmu__AccessCredential__Password= GMU Entegrasyonu için ortam bazlı değişkenlik gösteren GMU kullanıcısının şifresi
* Gmu__EMailServiceProductId=3
* Gmu__OwnerProductId=12
- ForwardedHeaderName=x-envoy-original-path
- Keycloak__TokenUrl=Keycloak kullanılıyor ise
 token isteğinin atıldığı endpoint
- Keycloak__EndpointUrl=Keycloak kullanılıyor ise base url bilgisi
- Keycloak__AccessCredential__Username=Keycloak kullanılıyor ise konfigurasyonunda verilen kullanıcı adı
- Keycloak__AccessCredential__Password=Keycloak kullanılıyor ise konfigurasyonunda verilen şifre
* CryptoSecret=Kriptolama için kullanılan random 32 byte binary secret key'in base64'e çevrilmiş formu, kendinize özel üretmeniz önerilir. Sonradan değiştirmemelisiniz
- Job__CancelChecksDailyJobCron= CancelChecksDailyAsync Job'ının Cron formatındaki çalıştırılma saati. https://crontab.guru/ sitesindeki formata uygun bir şekilde istenilen saat verilir.(Örneğin : 0 0 * * *). Eğer boş bırakılırsa varsayılan değerler çalışır.
- Job__DeactivateInActiveBranchesAndDevicesJobEnabled= true/false. DeactivateInActiveBranchesAndDevices Job'ının aktif olup olmadığının bilgisi. Varsayılan değer false. GMU tarafındaki DeactivateInactiveDevicesAndStoresJob Hangfire Job'ı aktif değilse bu job'ın aktif edilmesi bir anlam ifade etmez.
- Job__DeactivateInActiveBranchesAndDevicesJobCron= DeactivateInActiveBranchesAndDevices Job'ının Cron formatındaki çalıştırılma saati. https://crontab.guru/ sitesindeki formata uygun bir şekilde istenilen saat verilir.(Örneğin : 30 2 * * *). Eğer boş bırakılırsa varsayılan değerler çalışır.
- ExposeSensitiveLogs= Hassas veri içeren logların açık şekilde basılması isteniyor ise "true" değeri girilmelidir. Varsayılan değeri "false".
* HMACSecret= Android client GMU Rest Api ile mesajlaşma esnasında MITM (Man In The Middle) attack'a karşı HMAC (Keyed-Hash Message Authentication Code) kullanır. Buraya girilen secret ile Android SDK'ya init aşamasında pasgeçilen secret aynı olmalı. Secret herhangi bir random hex generator ile vb oluşturulabilir veya GMU API konfigürasyonundaki GMU_HMACSecret değeri aynen burada da kullanılabilir. İşletici kuruluşun her ortamında aynı değere sahip olmalıdır. Örnek: b136156ef7599b08ede5c025cdfbf8a9 gibi.
- DisableHmacAuth= true veya false olabilir, tanımlanmamışsa varsayılan değeri false. Değer girilmemiş ise veya false seçilmiş ise HmacAuth kontrolu aktif, eğer true girilmiş işe HmacAuth kontrolü yapılmaz.
- RedisConnectionString= Opsiyonel Redis bağlantı bilgileri. Format: addres:port,defaultDatabase=1,password= Birden fazla adres desteği vardır: addres1:port1,addres2:port2,defaultDatabase=1,password= gibi
- RedisPassword= Redis kullanılıyorsa Redis şifresi, k8/openshift secret olarak verilirse daha güvenli olur
- RedisCertificateFullPath= Opsiyonel Redis Client'ın TLS desteği için kullanacağı sertifikanın dosya yolu. Eğer boş bırakılır ise TLS olmadan bir bağlantı kurulur.
- EnableTokenBlacklisting= Auth token'ların kara listeye alınmasını sağlar. Aktif olarak kullanabilmek için "RedisConnectionString" ve "RedisPassword" dolu olmalıdır. Varsayılan değeri false'dur.

* Tüm ihtiyaç duyulan sistemler oluşturulduktan sonra ise Proje için gerekli olan Migration sorguları elle sistem
 için teker teker tarih sırasına göre çalıştırılarak sistem tabloları aktif hale getirilir.
* Sistem tabloları aktif hale geldikten sonra Hangfire için açılmış olan veri tabanında Hangfire Migration sorgusu
 elle çalıştırılır ve Hangfire hazır hale getirilir.
* Kurulum sonrası ise envoy var ise 'https://*/api/v1.0/docs/index.html' yoksa 'https://*/docs/index.html' adresinden
 test yapılabilir.
* Sistem içerisinde health check olarak ise 'http://*/health/live' kullanılabilir.

KeyCloak​

image : jboss/keycloak:13.0.1

ortam değişkenleri:

  • name: KEYCLOAK_USER (KeyCloak username admin verilebilir) value: ???
  • name: KEYCLOAK_PASSWORD (admin verilebilir) value: ???
  • name: DB_VENDOR (mssql,mysql vb.) value: ???
  • name: DB_USER value: ???
  • name: DB_PASSWORD value: ???
  • name: DB_ADDR value: ???
  • name: DB_DATABASE value: ???
  • name: PROXY_ADDRESS_FORWARDING (Keycloak'ı bir proxy arkasında çalıştırırken, bu değişkeni etkinleştirmeniz gerekir.) value: "true"
  • name: JAVA_OPTS_APPEND (profile features özelliklerini etkinleştirir.) value: -Dkeycloak.profile.feature.upload_scripts=enabled

Belirtilen ortam değişkenleri ve image ile deployment manifest oluşturulup cluster'da pod oluşturulur.

Envoy​

image: envoyproxy/envoy:v1.21.0

Yukarıda belirtilen image base image alınarak gerekli sertifika ve envoy.yaml (yönlendirmeler bu dosya içerisinde yapılır) dockerfile'da container içerisine ilgili yerlere copy edilerek container ayağa kaldırılır. Docker-compose ile oluşturulabilir

Örnek bir envoy.yaml iletiebilir

Envoy Dockerfile

FROM envoyproxy/envoy:v1.21.0

COPY ./???.key /etc/envoy/certs/???.key COPY ./???.key /etc/envoy/certs/???.key RUN rm -rf /etc/envoy/envoy.yaml COPY ./envoy.yaml /etc/envoy/envoy.yaml

Keycloak Hakkında​

Realms 

- Keycloacku kullanmaniz icin olusturmaniz gereken alandir.Realm sayesinde client, role, user gibi alanlari olusturulmasi
 ve yonetilmesi saglanir.

Realm Setting 

- Olusturdugumuz realmin alanlarinin bulundugu yerdir. Burada email, token ayarlarini yapariz.

Clients 

- Kullanicinin keycloackta authentication olmasi icin kullanilan alandir.Burda clienttan kasit, frontend , mobile vb gibi
 uygulamalardir.
- Olusturdugumuz clientin ayarlarinida yine bu sekmede olusturdugumuz clientin detayinda yapariz.
- Settings = Token almamiz icin clientin ayarlarinin yapildigi bolumdur. CliendId, client protokol,accesstype vb..
- Credential = Client auth olurken clientid ve secret gibi token alirken olmasi gereken alanlarin ayarlamalarinin yapildi
alandir.
- Mapper = Token alirken token icinde yer alacak bilgilerin girildigi alandir.

ClientScope 

- Clienta ait scopelarin tanimlandigi alandir. Bu scopelar clientin aldigi tokenda yer alir.Eger clientin tokeninda
 tanimladigimiz scopelardan bazilari yoksa o scope ait islemleri gerceklestiremezsiniz.

Ornek - agent/Discount.apply ---> bu scope yok ise ceke indirim uygulama yetkiniz yok demektir.
    agent/Order.listBranch
    agent/Order.refund
    agent/Payment.cash
    agent/Payment.creditCard
    branchMangement/Discount.create
    branchMangement/Product.assign
    branchMangement/Product.create
    branchMangement/ProductGroup.assign
    branchMangement/ProductGroup.create
    branchMangement/Report.manager
    branchMangement/Report.read

Roles 

- Rollerin Tanimlandigi alandir. 

Ornek - Admin   -- Admin apidaki islemler icin 
    Agent   -- Agent apidaki islemler icin
    BranchAdmin -- BranchAdmin apidaki islemler icin
bunlardan admin yetkisi kullanicinizda tanimli degilse admin api herhangi bir islem gerceklestiremezsiniz.

Users 

- Kullanicilarin kayitlarinin tutuldugu ve kayit yapildigi yerdir.Ayrica kullanicinin hangi rolleri kullanacagi token
 alirken hangi sifreyi kullanacagi gibi bilgiler buradan belirlenir.

Daha fazla bilgi icin

https://www.keycloak.org/guides

https://www.keycloak.org/documentation

Database Kurulum

  • Tüm veritabanlarında collation: Latin1_General_CI_AS

  • Müşterilere kurulan veritabanlarında, isimlendirdeki sadece son kısım verecekleri isimde geçse bakım kolaylığı açısından yeterli. Örneğin Hangfire veritabanında Hangfire, Master veritabanında Master lafzı geçmesi yeterli, diğer kısımları müşteri istediği şekilde belirleyebilir.

  • GMUPOS veritabanı önerilen isim formatı; production için: GMUPOS_Prod, test: GMUPOS_Test, staging: GMUPOS_Staging

  • GMUPOS Hangfire veritabanı önerilen isim formatı; production için: GMUPOS_Prod_Hangfire , test: GMUPOS_Test_Hangfire, staging: GMUPOS_Staging_Hangfire -> distributed job scheduler veritabanı

    HangFire isminde bir şema ihtiyacı vardır, Hangfire veritabanı için gönderdiğimiz dbscript bu şemayı kendisi açmaktadır.

  • GMUPOS Healthcheck veritabanı önerilen isim formatı; production için: GMUPOS_Prod_HealthCheck , test: GMUPOS_Test_HealthCheck, staging: GMUPOS_Staging_HealthCheck -> healthcheck sonuçları saklanır, unhealty olma geçmişi tutulur.

  • GMUPOS Keycloak veritabanı önerilen isim formatı; production için: GMUPOS_Prod_Keycloak, test: GMUPOS_Test_Keycloak, staging: GMUPOS_Staging_Keycloak

En son tarihinde güncellendi